Integrated Shipping

This feature improves the customer experience by embedding your shipping options directly into the Clearpay Express Checkout flow.

We recommend the Integrated Shipping flow for merchants with:

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

Integrated Shipping is configured in the call to initializeForPopup triggered by the Express Checkout button.

It requires addressMode to be an option that contains shipping options (see address modes with shipping options below) and an onShippingAddressChange callback must be defined:

AfterPay.initializeForPopup({
  // ...
  addressMode: AfterPay.ADDRESS_MODES.ADDRESS_WITH_SHIPPING_OPTIONS,
  onShippingAddressChange: function (data, actions) {
    /* address in `data` */
    /* calc options, then call `actions.resolve(options)` */
  }
});

📘
Note
If no addressMode is specified, the mode ADDRESS_WITH_SHIPPING_OPTIONS is enabled by default for Express orders. To change it, the addressMode can be set to one of the alternative addressMode options.

Address Mode

To support different shipping types in the checkout, configure the property addressMode with a provided constant. These constants are of the form AfterPay.ADDRESS_MODES.<NAME>, where <NAME> is one of the constants in the tables:

Constant (with shipping options)	Description
ADDRESS_WITH_SHIPPING_OPTIONS	This is the default configuration. It displays at checkout so the customer can optionally configure their shipping address. They can also select from the merchant’s list of available shipping options.
SHIP_TO_ORDER_ADDRESS	Displays at checkout with the chosen customer shipping address and the ability to select from the merchant’s list of available shipping options. See preselected shipping address order for more details.
PICKUP_FROM_ORDER_ADDRESS	Displays at checkout with the chosen merchant pickup address for the order. See pickup orders for more details.

Constant (without shipping options)	Description
ADDRESS_WITHOUT_SHIPPING_OPTIONS	Displays at checkout with the option for the customer to configure their shipping address only. The customer intends to continue their order back on the merchant website.
SHIP_TO_ORDER_ADDRESS_WITHOUT_SHIPPING_OPTIONS	Displays checkout with the option for the customer to configure their shipping address only with the intention to buy now.
NO_ADDRESS	For checkouts that require no address for the product to be delivered to (eg.digital goods). This displays at checkout without the address and shipping option sections.

AfterPay.initializeForPopup({
  // ...
  addressMode: AfterPay.ADDRESS_MODES.NO_ADDRESS,
})

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

AfterPay.initializeForPopup({
  // ...
  shippingOptionRequired: true,
  onShippingAddressChange: function (data, actions) {
    /* address in `data` */
    /* calc options, then call `actions.resolve(options)` */
  },
});

🚧
Warning - Cross Border Trade
For cross border trade orders, the shipping costs and taxes must be returned in the same currency in which the checkout is initiated. For example:
Imagine you are a British merchant displaying a 100 GBP order in EUR for a French customer on your site. When starting Clearpay checkout, if you start checkout by sending us the order amount in GBP (e.g. 100 GBP), then you must also send us the shipping costs and taxes in GBP as part of the onShippingAddressChange callback. Likewise, if you initiate checkout by sending us the order amount in EUR post currency conversion on your side (e.g. 120 EUR), ensure that the shipping costs and taxes are also sent in EUR.
Always ensure that the currency is consistent throughout the entire checkout flow.

Restrictions

The Integrated shipping feature is currently only available with popup and is not yet supported in the redirect flow.

Listening for Address Changes

The Shipping Address Change callback is a feature of the Express Checkout. This callback allows a merchant to dynamically update shipping options and taxes based on the shipping address chosen by the customer.

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.

How the shipping options are calculated is entirely managed by the merchant. The merchant can use Javascript for the calculation or use an internal API.

If shipping options are available for the given address, use the resolve action to return them to Clearpay. This is shown in the code example below. Similarly, use the reject action when shipping is unavailable.

Example retrieving shipping options via API

AfterPay.initializeForPopup({
  // ...
  onShippingAddressChange: function (data, actions) {
    fetch('/your-shipping-endpoint', {
      method: 'POST',
      headers: { 'content-Type': 'application/json' },
      body: JSON.stringify(data),
    }).then(function(options) {
      actions.resolve(options)
    }).catch(function(error) {
      // Parse the response and send an AfterPay rejection, e.g.:
      actions.reject(AfterPay.CONSTANTS.SHIPPING_UNSUPPORTED)
    })
  },
})

Example calculating shipping options in JS

AfterPay.initializeForPopup({
  // ...
  onShippingAddressChange: function (data, actions) {
    if (data.countryCode !== 'AU') {
      // Reject any unsupported shipping addresses
      actions.reject(AfterPay.CONSTANTS.SHIPPING_UNSUPPORTED)
    } else {
      // Calc shipping inline
      actions.resolve([ {
        id: '1', name: 'Standard', description: '3 - 5 days',
        shippingAmount: { amount: '0.00', currency: 'AUD'},
        taxAmount: { amount: '3.18', currency: 'AUD'},
        orderAmount: { amount: '34.99', currency: 'AUD'},
      }, {
        id: '2', name: 'Priority', description: 'Next business day',
        shippingAmount: { amount: '10.99', currency: 'AUD'},
        taxAmount: { amount: '4.28', currency: 'AUD'},
        orderAmount: { amount: '47.08', currency: 'AUD'},
      } ])
    }
  },
})

The Data Argument

Property	Type	Description
`name`	String	Full name of the customer.
`address1`	String	First line of the address.
`address2`	String	Second line of the address.
`area2`	String	Village/local area of the address.
`suburb`	String	Suburb/City of the address.
`state`	String	AU: State, NZ: Region, UK: County, US: State, CA: Province or Territory.
`postcode`	String	ZIP or postal code. If the country does not have postcodes, the countryCode is sent as the value instead.
`countryCode`	String	The ISO 3166-1 alpha-2 country code.
`phoneNumber`	String	The phone number in E.123 format.

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.:

actions.reject(AfterPay.CONSTANTS.SHIPPING_UNSUPPORTED)

Listening for Warning/Error messages

To facilitate handling of logging/warning/error messages, AfterPay.onMessage can optionally be replaced with a custom function. The default function is:

AfterPay.onMessage = function (payload) {
  console[payload.severity](payload.message)
}

Shipping Option Model

Attribute	Type	Description
`id`	String (required)	A shipping option identifier. Max length 128.
`name`	String (required)	The name of the shipping options.
`shippingAmount`	Money (required)	The shipping amount (without tax, if including `taxAmount`).
`taxAmount`	Money (required)	The tax amount.
`orderAmount`	Money (required)	The total amount for the order including shipping and taxes.
`description`	String	A description for this shipping optio

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 is one of:

Constant	Description
`SHIPPING_ADDRESS_UNRECOGNIZED`	Unrecognised address.
`SHIPPING_ADDRESS_UNSUPPORTED`	Recognised address, but will not ship there.
`SERVICE_UNAVAILABLE`	General service error.

Note

Afterpay Express Checkout does not do arithmetic. It is your web app that must calculate the correct total. Each shipping option must have a total order amount including taxes and shipping.

Listening for Shipping Option Changes

The onShippingOptionChange callback is optional. It allows you to track the customer’s chosen shipping option as it changes. It is called with a single Shipping Option argument each time the customer selects a shipping option. See code example below:

AfterPay.initializeForPopup({
  // ...
  onShippingOptionChange: function (data) {
    console.log(data)
  },
})

Updating the chosen shipping option

If you want the shipping option amounts to be modified once the customer has selected a shipping option, onShippingOptionChange can take an additional action argument. This argument can inform the checkout of these changes.

When the call to onShippingOptionChange happens:

Use the shipping option data and make the required modification (eg. contact your backend api to recalculate the tax value of the selected shipping option).

Once you have an updated shipping option you should:

Use actions.resolve to return an object that contains:

id - this should be the same shipping option ID as received in onShippingOptionChange
shippingAmount- the updated shipping amount of the selected shipping option
taxAmount - the updated tax amount of the selected shipping option
orderAmount- the updated order amount of the selected shipping option
to the Afterpay Express checkout, or use actions.reject to signal an error

AfterPay.initializeForPopup({
  // ...
  onShippingOptionChange: function (data, action) {
      fetch('/your-update-shipping-option-endpoint', {
          method: 'POST',
          headers: { 'content-Type': 'application/json' },
          body: JSON.stringify(data),
      }).then(function(options) {
          actions.resolve({
             id: data.id, 
             shippingAmount: { amount: '0.00', currency: 'AUD'},
             taxAmount: { amount: '3.18', currency: 'AUD'},
             orderAmount: { amount: '34.99', currency: 'AUD'},
          })
      }).catch(function(error) {
          // Parse the response and send the error, e.g.:
          actions.reject(error)
      })
  },
})

The onShippingOptionChange actions argument

Property	Type	Description
`resolve`	Function	Call this method to send the modified shipping option. Takes a single shipping option, see the Shipping Option model to be resolved for `onShippingOptionChange` table below.
`reject`	Function	Call this method when you are unable to handle the request.

Shipping Option model to be resolved for onShippingOptionChange

Attribute	Type	Description
`id`	String (required)	The shipping option identifier. This should match the ID of the shipping option you are updating.
`shippingAmount`	Money (required)	The updated shipping amount (without tax, if including taxAmount).
`taxAmount`	Money (optional)	The updated tax amount.
`orderAmount`	Money (required)	The updated total amount for the order including shipping and taxes.

Optional Integrated Shipping Features

These are described on a separate page called Optional Integrated Shipping Features.

Integrated Shipping

📘
Note

Address Mode

🚧
Warning - Cross Border Trade

Restrictions

Listening for Address Changes

Listening for Warning/Error messages

Shipping Option Model

Shipping Constants

Listening for Shipping Option Changes

Updating the chosen shipping option

Optional Integrated Shipping Features

📘Note

Address Mode

🚧Warning - Cross Border Trade

Restrictions

Listening for Address Changes

Listening for Warning/Error messages

Shipping Option Model

Shipping Constants

Listening for Shipping Option Changes

Updating the chosen shipping option

Optional Integrated Shipping Features

📘
Note

🚧
Warning - Cross Border Trade