Shipping options in Checkout Express

Checkout Express lets the merchant list multiple shipping options so their customers can select their preferred shipping option. The shipping options will be listed in the order they appear in the express.shipping_options array. 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 different pick_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 appearance in the UI. The following documentation will go through each possible addition 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+02:00",
        "ends_at": "2025-02-10T17:00:00+02: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
        }
    ]
}

Providing more details to a shipping option

Delivery method

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 user flow.

{
    "delivery_method": "delivery" | "pick_up" | "unspecified" | "none"
}

Estimated time of arrival

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+02:00",
        "ends_at": "2035-09-01T00:00:00+02:00"
    }
}

Pick up address

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": 59.9500157,
        "longitude": 10.7663589,
        "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": 1.5
    }
}

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"
            }
        ]
    }
}

Shipping operator branding

Checkout by default provides iconography for the most common shipping 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`

Grouping shipping options

Similar shipping options can be grouped to improve the user experience. To group multiple shipping options the following requirements need to be met:

All items within a single group has to use the same values for id, title, amount and delivery_method and operator.
The delivery_method has to be either delivery or pick_up.
If delivery_method is set to delivery a time_slot needs to be set for each option in the group.
If delivery_method is set to pick_up a pick_up_address needs to be set for each option in the group.

Grouped delivery options with different time slots

See also the section on time slots on how to specify a time slot.

Grouped pick up options with different pick up addresses

See also the pick up address example for more information on what properties are supported.

Restricting a 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"]
}

Splitting the payment of a shipping option

Similar to how items behave with splits, the same applies for a shipping option. Instructions for using split

Pay in store

Instructions for 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": "Will 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 callback when the end user 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"
            }
        ]
    }
}

Multiple shipments

If the order contains multiple shipments please see the the guide for how to handle multiple shipments.

Checkout Integration

Express Checkout

Payment Methods

Tokenization

Split Payout

In-Person Payments

Shipping options in Checkout Express

Providing more details to a shipping option

Delivery method

Estimated time of arrival

Time slot

Pick up address

Environmental data

Shipping operator branding

List of operators in which iconography is provided by Checkout:

Grouping shipping options

Grouped delivery options with different time slots

Grouped pick up options with different pick up addresses

Restricting a shipping option to a set of countries

Splitting the payment of a shipping option

Pay in store

Sessions without shipping options or hiding the shipping option

Dynamic and static shipping options

Specifying a default shipping option

Multiple shipments

​Providing more details to a shipping option

​Delivery method

​Estimated time of arrival

​Time slot

​Pick up address

​Environmental data

​Shipping operator branding

List of operators in which iconography is provided by Checkout:

​Grouping shipping options

​Grouped delivery options with different time slots

​Grouped pick up options with different pick up addresses

​Restricting a shipping option to a set of countries

​Splitting the payment of a shipping option

​Pay in store

​Sessions without shipping options or hiding the shipping option

​Dynamic and static shipping options

​Specifying a default shipping option

​Multiple shipments

Providing more details to a shipping option

Delivery method

Estimated time of arrival

Time slot

Pick up address

Environmental data

Shipping operator branding

Grouping shipping options

Grouped delivery options with different time slots

Grouped pick up options with different pick up addresses

Restricting a shipping option to a set of countries

Splitting the payment of a shipping option

Pay in store

Sessions without shipping options or hiding the shipping option

Dynamic and static shipping options

Specifying a default shipping option

Multiple shipments