Integrated Shipping

This feature improves the customer experience by embedding your shipping options directly into the Express Checkout flow. It streamlines the checkout process and can be combined with the buyNow flag to create a one-step checkout that immediately precedes the order confirmation page.

We recommend the Integrated Shipping flow for merchants with:

• Fewer than 5 shipping options
• Single shipping option for an entire order (i.e. no SKU level options)
• Simple tiered shipping options (e.g. standard, express, rush)
• Pickup in-store option before checkout entry

It requires shippingOptionRequired to be true (enabled by default) and an onShippingAddressChange callback must be defined:

1
const afterpayButton = document.getElementsByTagName('afterpay-button')[0];
2
afterpayButton.addEventListener('click',
3
   function (e) {
4
        // ...all attributes listed in step 4 above,
5
        afterpayButton.expressCheckout = {
6
          region: 'US',
7
          onShippingAddressChange: function (data, actions) {
8
           /* required for Integrated Shipping  */
9
           /* address in `data` */
10
           /* calc options, then call `actions.resolve(options)` */
11
         },
12
         onShippingOptionChange: function (data) {
13
           /* optional - chosen option in `data` */
14
         },
15
           onComplete: function (data) {
16
           /* handle success/failure of checkout */
17
         },
18
         buyNow: false,
19
         pickup: false,
20
         shippingOptionRequired: true
21
        }
22
23
   }, true
24
);

Listening for Address Changes

The shipping address change callback is required:

• If you intend to update the order total based on a chosen shipping address.
• To validate that you can ship to the selected address.
  To set up the Shipping Address Change callback, implement the onShippingAddressChange function. This function is passed two arguments: data and actions.

You, the merchant, manage how the shipping options are calculated. Javascript can calculate the options, or you can pass them to an internal API.

If shipping options are available for the given address, use the resolve action to return them to Afterpay, Clearpay (UK) or Cash App Afterpay (US) - see the code example below. Similarly, use the reject action when shipping is unavailable.

Example of retrieving shipping options via API

1
onShippingAddressChange: function (data, actions) {
2
    fetch('/your-shipping-endpoint', {
3
      method: 'POST',
4
      headers: { 'content-Type': 'application/json' },
5
      body: JSON.stringify(data),
6
    }).then(function(options) {
7
      actions.resolve(options)
8
    }).catch(function(error) {
9
      // Parse the response and send an AfterPay rejection, e.g.:
10
      actions.reject(AfterPay.CONSTANTS.SHIPPING_UNSUPPORTED)
11
    })
12
  },

Example of calculating shipping options in JS

1
onShippingAddressChange: function (data, actions) {
2
    if (data.countryCode !== 'US') {
3
      // Reject any unsupported shipping addresses
4
      actions.reject(AfterPay.CONSTANTS.SHIPPING_UNSUPPORTED)
5
    } else {
6
      // Calc shipping inline
7
      actions.resolve([ {
8
        id: '1', name: 'Standard', description: '3 - 5 days',
9
        shippingAmount: { amount: '0.00', currency: 'USD'},
10
        taxAmount: { amount: '3.18', currency: 'USD'},
11
        orderAmount: { amount: '34.99', currency: 'USD'},
12
      }, {
13
        id: '2', name: 'Priority', description: 'Next business day',
14
        shippingAmount: { amount: '10.99', currency: 'USD'},
15
        taxAmount: { amount: '4.28', currency: 'USD'},
16
        orderAmount: { amount: '47.08', currency: 'USD'},
17
      } ])
18
    }

Afterpay calls your onShippingAddressChange function when:

• The customer first enters the Afterpay summary page
• The customer makes a change to their shipping address on the Afterpay summary page

Afterpay provides the following parameters to your onShippingAddressChange function:
data parameter: This contains the customer’s selected address with fields:

• suburb, state, postcode, and countryCode

action parameter: This object is used to return your response to the Afterpay checkout. It consists of the following methods:

• resolve : Call this method to provide the shipping options applicable to the customers address. Takes an array of Shipping Option objects.
• reject : Call this method when you are unable to handle the request. Do not throw an error, instead call this method with a Shipping Constant as the first argument to indicate a status, e.g.:

1
actions.reject(AfterPay.CONSTANTS.SHIPPING_UNSUPPORTED)

Shipping Option Model

Shipping Constants

To indicate a number of error scenarios, actions.reject() may be invoked with a provided constant.

These are of the form AfterPay.constants.<NAME>, where <NAME> is one of:

Listening for Shipping Option Changes

The onShippingOptionChange callback allows a merchant to track the customer’s chosen shipping option as it changes. It is optional, and is called each time a customer selects a shipping option. This function is passed one argument: data

data parameter (object): This contains the customer’s selected shipping option, as provided in the response from onShippingAddressChange, with fields:

1
onShippingOptionChange: function (data) {
2
    console.log(data)
3
  },

Buy Now

When the Express Checkout is complete, you may either authorize the virtual credit card provided by Afterpay or continue checkout on your review page. If you completing the order immediately, set the buyNow flag to true - this shows the customer a “Buy Now” button at the end of their Afterpay journey.

1
const afterpayButton = document.getElementsByTagName('afterpay-button')[0];
2
afterpayButton.addEventListener('click',
3
   function (e) {
4
        // ...all attributes listed in step 4 above,
5
        afterpayButton.expressCheckout = {
6
          // ...
7
          buyNow: true,
8
        }
9
   }, true
10
);

Configuring a pickup order

You can modify the Express Checkout experience for Click & Collect and other pickup flows by following these steps:

1. Allow your customers the ability to choose pickup options before they select Afterpay Express. This should include any decisions that may affect the cost of delivery, for instance pickup location and date.

2. If the customer has opted for pickup, provide the chosen pickup address when adding the shipping attributes.

3. When you include the expressCheckout object attribute:

   • Set the pickup flag to true.

   • Configure your onShippingAddressChange handler to return the name and description of their pickup choice. This will likely mean returning only a single option — e.g

   1
   actions.resolve([ {
   2
     id: 'pickup-store-123', name: 'Click & Collect',
   3
     description: 'Available for next-day pickup',
   4
     shippingAmount: { amount: '0.00', currency: 'USD'},
   5
     taxAmount: { amount: '3.18', currency: 'USD'},
   6
     orderAmount: { amount: '34.99', currency: 'USD'},
   7
   } ])

4. You can collect additional information regarding the pickup, e.g. selecting another person to pick up the order, at your order review page. These details must not increase the order total.