Shipping options
Checkout Express lets the merchant list multiple shipping options so their customers can select their preferred shipping option.
Each shipping option needs a minimum set of required declared properties:
{
"id": "group-id",
"line_id": "unique-shipping-id",
"amount": 10000,
"operator": "shipping-provider-name",
"title": "Home delivery"
}
id: ID of the shipping option product. This ID does not have to be unique as it will be used by Checkout to group together shared shipping option products that deliver to same address at different time slots, or shipping options that have the same name and amount but differentpick_up_address.line_id: The unique ID of the specific configuration of the shipping option product. This will be used to identify the selected shipping option in the order.amount: The monetary amount of the shipping option, including VAT and discounts in the smallest unit of the session currency.operator: Name of the company that provides shipping service.title: The title of the shipping option. For example, "Standard home delivery".
Shipping options can be configured in several ways allowing for flexible configuration and appearence in the UI. The following documentation will go through each possible additions to the shipping option, in which all of them are optional but contribute to a better checkout experience for the customer.
{
...
"countries": ["NO", "SE"],
"vat_amount": 2500,
"vat": 25,
"description": "Fastest delivery service to your doorstep",
"delivery_method": "delivery",
"operator_product_id": "shipping-product-id",
"eta": {
"working_days": [1,5]
},
"time_slot": {
"starts_at": "2025-02-06T12:00:00",
"ends_at": "2025-02-10T17:00:00"
},
"pick_up_address": {
"first_name": "John",
"last_name": "Doe",
"address_line": "Address",
"address_line_2": "Address 2",
"co_address": "Land Lord",
"business_name": "Business name",
"postal_code": "0349",
"postal_place": "Oslo",
"country": "NO",
"phone_number": "+47XXXXXXXX",
"email": "email@example.com",
"latitude": 0,
"longitude": 0,
"comment": "Comment about pick up address",
"organization_number": "XXXXXXXX",
"organization_type": "XX",
"customer_reference": "Ref.",
"cost_center": "Cost center specification",
"website_url": "http://example.com",
"opening_hours": {
"open_now": true,
"periods": [
{
"opens_at": "08:00",
"closes_at": "16:00",
"day_of_week": 1
}
],
"timezone": "Europe/Oslo"
},
"distance": 0
},
"metadata": {
"operator_dest": "XAB1239",
"number_x": 1921
},
"environmental_data": {
"description": "Fossil free",
"details": [
{
"label": "Carbon offset",
"value": "1KG CO2"
}
]
},
"thumbnail_url": "http://example.com",
"pay_in_store": {
"type": "full"
},
"fee_split": {
"type": "proportional",
"destinations": [
"string"
]
},
"splits": [
{
"payout_destination_id": "seller-id",
"amount": 29700
}
]
}
Restricting shipping option to a set of countries
A session can contain multiple shipping options catered towards different countries and still provide only the relevant shipping options available for the customer.
For example, to make a shipping option only appear for Norwegian customers, add the following to the configuration:
{
"countries": ["NO"]
}
This will restrict the shipping option to only be available for Norwegian customers when entering Checkout. Other shipping options that do not have this specified are not affected.
Multiple countries can also be added. In the following example, the shipping option will only be available to Norwegian and Swedish customers.
{
"countries": ["NO", "SE"]
}
Providing more details to a shipping option
A shipping option can be characterised by delivery method, pay_in_store, or by title alone in tandem with description.
delivery_method states what type of delivery the shipping option product is and should be supplemented with additional details such as pick_up_address, eta and/or time_slot for optimal userflow.
{
"delivery_method": "delivery" | "pick_up | "unspecified" | "none"
}
Giving a time estimate
eta can be used to give the shipping option a time estimate. It can be specified as a date-time range by setting the starts_at and ends_at date-times. If the dates in starts_at and ends_at are different, the checkout will only show the dates, if the dates are the same the checkout will also show the time specified.
{
"eta": {
"starts_at": "2021-09-01T00:00:00Z",
"ends_at": "2035-09-01T00:00:00Z"
}
}
Or a working days estimate:
{
"eta": {
"working_days": [1, 2]
}
}
Or an estimated arrival/shipping on the day of the week, or in combination:
{
"eta": {
"arrival_day_of_week": 2,
"shipping_day_of_week": 2,
"working_days": [1, 2]
}
}
working_days can be used to describe the lowest estimated amount of working days and the highest estimated amount of working days needed for the shipping process. The array corresponds to the display of n-n in Checkout. A range of [0, 0] will correspond to a shipment that occurs today or next possible working day.
(arrival|shipping)_day_of_week can be used when shipment or arrival of items occurs during a day of the week. The value corresponds to the order of the day in a week by European conventions. For instance, a shipping option that ships on fridays would have shipping_day_of_week set to 5 as Friday is the fifth day in a week going from Monday to Sunday.
starts_at and ends_at can be used to provide an absolute time estimate of the shipping option.
Time slot
time_slot provides the shipping option with a specified time of delivery to the customer.
{
"time_slot": {
"starts_at": "2021-09-01T00:00:00",
"ends_at": "2035-09-01T00:00:00"
}
}
Address details
pick_up_address can be used to provide address details of where the items will be delivered by a shipping option. All of the fields are optional to include, but provide sufficient context to the shipping option.
{
"pick_up_address": {
"first_name": "John",
"last_name": "Doe",
"address_line": "Address",
"address_line_2": "Address 2",
"co_address": "Land Lord",
"business_name": "Business name",
"postal_code": "0349",
"postal_place": "Oslo",
"country": "NO",
"phone_number": "+47XXXXXXXX",
"email": "email@example.com",
"latitude": 0,
"longitude": 0,
"comment": "Comment about pick up address",
"organization_number": "XXXXXXXX",
"organization_type": "XX",
"customer_reference": "Ref.",
"cost_center": "Cost center specification",
"website_url": "http://example.com",
"opening_hours": {
"open_now": true,
"periods": [
{
"opens_at": "08:00",
"closes_at": "16:00",
"day_of_week": 1
}
],
"timezone": "Europe/Oslo"
},
"distance": 0
}
}
Providing environmental data
A shipping option can include details on how big of an environmental impact the shipping process will be by declaring environmental_data. This will be shown in Checkout within a tooltip beneath the label "Climate smart".
{
"environmental_data": {
"description": "Carbon neutral delivery",
"details": [
{
"label": "Carbon offset",
"value": "0.5 kg CO2e"
},
{
"label": "Trees planted",
"value": "3"
}
]
}
}
Providing branding
Checkout by default provides iconography for a set of common operators, but if there's a need for a custom logo on the shipping option then thumbnail_url can be used.
List of operators in which iconography is provided by Checkout:
| Operator | Value |
|---|---|
| Posten | posten |
| Bring | bring |
| Helthjem | helthjem |
| Postnord | postnord |
| Gordon | gordon |
| DHL | dhl |
| UPS | ups |
| FedEx | fedex |
| DB Schenker | dbschenker |
| Dachser | dachser |
| Budbee | budbee |
| PorterBuddy | porterbuddy |
| TNT | tnt |
| Instabox | instabox |
Splitting the payment of a shipping option
Similar to how items behave with splits, the same applies for a shipping option.
Pay in store
Sessions without shipping options or hiding the shipping option
The shipping option selection can skipped if the order does not have shipping, like a service or a digital product. This can be achieved by setting the shipping_mode on the session in the session.express object to shipping_not_required and set the shipping_options to an empty array.
{
...,
"express": {
"shipping_options": [],
"shipping_mode": "shipping_not_required"
}
}
Another option for hiding or not displaying the shipping option in the checkout is to create a single shipping option that has the type set to none and the amount set to zero.
{
"id": "hidden",
"line-id": "single-hidden-shipping-option",
"title": "Willl not show up in the checkout",
"type": "none",
"amount": 0,
"operator": "none"
}
Dynamic and static shipping options
The shipping options are static if the shipping_address_callback_url is not defined. It has to be omitted from the json payload, so setting it to undefined (not valid json) or null or an empty string is not allowed.
{
...,
"express": {
"shipping_options": [...]
}
}
Use the shipping_address_callback_url to make the list shipping options in the checkout dynamic based on the customers address. A request will be sent to the calback when the end users submits or changes their address in the checkout. If the current address of the customer is not supported by the merchant (or their logistics operators) return an empty list to inform the checkout that delivery to the customers address is not possible.
For more information continue to the docs shipping callbacks documentation and the API spec for the address update.
Specifying a default shipping option
The Checkout will automatically select the first shipping option in the list of available shipping options if the selected shipping option is not specified in the session.order.
If a specific shipping option should be selected, add the shipping option in session.order:
{
"order": {
...,
"shipping_option": {
...,
"line_id": "shipping-line-id"
}
},
"express": {
"shipping_options": [
...,
{
...,
"line_id": "shipping-line-id"
}
]
}
}