> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dintero.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.dintero.com/feedback
```json
{
"path": "/docs/checkout/shipping-options",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Shipping options in Checkout Express
> Configure shipping options in Dintero Checkout Express with id, line_id, amount, and operator fields so customers can pick their preferred delivery option.
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:
```json theme={null}
{
"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.
```json theme={null}
{
...
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"eta": {
"starts_at": "2021-09-01T00:00:00Z",
"ends_at": "2035-09-01T00:00:00Z"
}
}
```
Or a working days estimate:
```json theme={null}
{
"eta": {
"working_days": [1, 2]
}
}
```
Or an estimated arrival/shipping on the day of the week, or in combination:
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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".
```json theme={null}
{
"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](#time-slot) on how to specify a time slot.
#### Grouped pick up options with different pick up addresses
See also the [pick up address example](#pick-up-address) 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:
```json theme={null}
{
"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.
```json theme={null}
{
"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`](/docs/checkout/split-payment/creating-split-session)
### Pay in store
[Instructions for `pay_in_store`](/docs/checkout/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.
```json theme={null}
{
...,
"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.
```json theme={null}
{
"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.
```json theme={null}
{
...,
"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](/docs/checkout/shipping-address-callback) and [the API spec for the address update](https://docs.dintero.com/payments-api.html#tag/example-session-callbacks/operation/example_shipping_address_callback_url).
### 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`:
```json theme={null}
{
"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](/docs/checkout/shipping-options-multiple-shipments).