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:

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

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

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:

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:

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

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

Shipping Option model to be resolved for onShippingOptionChange

Optional Integrated Shipping Features

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