> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developers-beta.clearpay.co.uk/v-2/llms.txt
> - v1: https://developers-beta.clearpay.co.uk/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers-beta.clearpay.co.uk/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers-beta.clearpay.co.uk/_mcp/server.

# Optional Integrated Shipping Features

## Pickup Orders

If you offer the customer a choice of pickup options before they enter Clearpay Express, e.g. at the cart level, you can send their choice to Clearpay. This displays the chosen pickup address and option within the Clearpay Express checkout and prevents the customer from choosing a different address.

To enable *Pickup Orders*, set the `addressMode` flag to `AfterPay.ADDRESS_MODES.PICKUP_FROM_ORDER_ADDRESS` in `initializeForPopup`, and send the pickup address in the shipping body parameter when the order is created:

```javascript
AfterPay.initializeForPopup({
  // ...
  addressMode: AfterPay.ADDRESS_MODES.PICKUP_FROM_ORDER_ADDRESS,
})
```

## Configuring a pickup order

The Express Checkout experience can be tailored for Click & Collect and other pickup flows by following these steps:

1. Allow your customers the ability to choose pickup options before they select Clearpay 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 creating the order via the **`shipping`** body parameter. For example:

```curl
curl --request POST \
  --url https://api.eu-sandbox.afterpay.com/v2/checkouts  \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"amount":{"amount":"10.00", “currency”: “GBP”}, “mode”: “express”, "merchant": {"popupOriginUrl": "https://example.com"}, "shipping": {"name": "Your Store Name", "line1": "123 Store Address", "postcode": "0000"}}'
```

3. When invoking `initializeForPopup`\
   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. For example:

```javascript
actions.resolve([ {
  id: 'pickup-store-123', name: 'Click & Collect',
  description: 'Available for next-day pickup',
  shippingAmount: { amount: '0.00', currency: 'GBP'},
  taxAmount: { amount: '3.18', currency: 'GBP'},
  orderAmount: { amount: '34.99', currency: 'GBP'},
} ])
```

* Depending on your configuration, your front end may have already invoked`initializeForPopup` before the front end knows whether the customer will opt for pickup. It is safe to invoke `initializeForPopup` multiple times; each call will overwrite the previous settings. In this case you may choose to call `initializeForPopup` in response to the customer selecting a pickup option.

4. You may choose to collect additional information regarding the pickup, e.g. choosing another person to pick up the order, at your order review page. These details must not affect the order total.

### International Shipping

This feature enables customers to choose international shipping addresses within the Clearpay Express Checkout flow. To configure the checkout to allow international addresses for shipping:

1. Specify `shippingOptions` in the body parameter when you create the order. This property should contain the following:

* `supportedShippingCountries` Contains the list of country codes in the two-character ISO 3166-1 format of all the countries you support as a destination for international shipping
* `shippingCountry` The country code in the two-character ISO 3166-1. As an option, you can set the default to a specific country in the dropdown selection of the *add new address* page

Create checkout V2 API call

```curl
curl --request POST \
  --url https://api-sandbox.afterpay.com/v2/checkouts \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"amount":{"amount":"10.00", “currency”: “AUD”}, “mode”: “express”, "merchant": {"popupOriginUrl": "https://example.com"}, "shipping": {"name": "Your Store Name", "line1": "123 Store Address", "postcode": "0000"}, shippingOptions: {
    "supportedShippingCountries": [
        "US",
        "AU",
        "GB",
        "BE",
        “CA”
    ],
   “shippingCountry”: “AU”
}}'
```

The `shippingOptions` data payload properties

| Property                     | Type   | Description                                                                                             |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `supportedShippingCountries` | String | An array of  ISO 3166-1 alpha-2 country codes.                                                          |
| `shippingCountry`            | String | The shipping country in  ISO 3166-1 alpha-2 format to be displayed initially when adding a new address. |

### Preselect Shipping Option

If customers have the option of choosing a shipping option on your site (before launching Clearpay Express Checkout), you can send us this information when checkout launches. This helps us reduce friction by preselecting the shipping option within the Clearpay flow.

To do this, set the shipping option ID in the `shippingOptionIdentifier` body parameter when the order is created. This enables the checkout to preselect that option if returned from the `onShippingAddressChange` when the checkout first loads.

Create checkout V2 API call

```curl
curl --request POST \
  --url https://api-sandbox.afterpay.com/v2/checkouts \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"amount":{"amount":"10.00", “currency”: “AUD”}, “mode”: “express”, "merchant": {"popupOriginUrl": "https://example.com"}, "shipping": {"name": "Your Store Name", "line1": "123 Store Address", "postcode": "0000"}, shippingOptionIdentifier: “standard”
}}'
```

| Property                 | Type   | Description                                                             |
| ------------------------ | ------ | ----------------------------------------------------------------------- |
| shippingOptionIdentifier | String | The ID of the shipping option to be preselected as the shipping option. |

## Preselected Shipping Address Orders

If you give the customer an option to enter/select their shipping address before a Clearpay Express checkout, you can send their choice to Clearpay. The customer's chosen shipping address appears within the Clearpay Express checkout and prevents the customer from choosing a different address.

Depending on whether you want to provide a list of available shipping options for that chosen shipping address, you must set the `addressMode` in `initializeForPopup` to one of the following:

* `AfterPay.ADDRESS_MODES.SHIP_TO_ORDER_ADDRESS` -  you will also need to follow the steps in [Integrated Shipping](/ec-int-shipping) to integrate shipping options for this mode
* `AfterPay.ADDRESS_MODES.SHIP_TO_ORDER_ADDRESS_WITHOUT_SHIPPING_OPTIONS`

Here are the code examples:

```javascript
AfterPay.initializeForPopup({
  // ...
  addressMode: AfterPay.ADDRESS_MODES.SHIP_TO_ORDER_ADDRESS,
})
```

Create checkout V2 API call.

Ensure that the shipping address the customer has chosen is sent in the `shipping` body parameter.

```curl
curl --request POST \
  --url https://api-sandbox.afterpay.com/v2/payments/capture \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"token": "YOUR_TOKEN", "amount":{"amount":"10.00", “currency”: “AUD”}}'
```