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, theaddressMode
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
, andcountryCode
- 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 inonShippingOptionChange
shippingAmount
- the updated shipping amount of the selected shipping optiontaxAmount
- the updated tax amount of the selected shipping optionorderAmount
- the updated order amount of the selected shipping option
to the Afterpay Express checkout, or useactions.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.
Updated 11 months ago