Skip to content

Shipping options in the checkout

Offer delivery choices in Kustom Checkout: live options from your TMS through the Shipping Assistant, or a fixed shipping_options list sent with the order.

Starting playground session…

On this page you'll

  • Choose between the Shipping Assistant and basic shipping options
  • Turn the Shipping Assistant on for your checkout
  • Send basic shipping options with the order and read back the customer's choice
This page runs for real. The order below executes against a live Playground merchant, in a checkout you can click through.Skip to the checkout ↓

Offer delivery choices from your transport management system (TMS) through the Shipping Assistant, or send a fixed list of basic shipping options with the order. This guide covers merchant setup. TMS providers should use Build a TMS integration.

  • Enable delivery. Set options.allow_separate_shipping_address to true, or send a non-empty shipping_options list, when you create the order. A list containing only an option with shipping_method: "Digital" doesn’t enable delivery.
  • Only physical goods are shipped. Lines with type: "physical", the default, need a delivery. A cart with nothing physical gets no delivery choice.
  • Read the selected option as selected_shipping_option, when you read the order.
  • Listen for changes. The shipping_option_change client-side event fires when the customer picks an option, with its name, price and tax. See Client-side events for how to listen for it.

Kustom adds the shipping fee unless you register a callback to calculate it:

  • Kustom adds it (the default). When the customer picks an option, Kustom adds a shipping_fee line, a zero-amount one for a free option, and raises order_amount and order_tax_amount to match. Don’t add it yourself or the fee is counted twice.
  • You add it, through a callback. Register merchant_urls.shipping_option_update and Kustom stops adding the fee. It calls you when the choice changes, and your response must include the shipping fee. Choose this when you need to control how tax is allocated on the shipping fee, for example when a cart mixes VAT rates. See Server-side callbacks.
Shipping AssistantBasic shipping options
Options come fromYour TMS, asked liveA fixed list on the order
Address and cart updatesKustom requests new options from the TMSYour integration updates the list on the order
Pickup points on a map, time slots, add-onsYesNo
Shipment reserved in your TMSYes, its id arrives as tms_referenceNo
What you set upA TMS and a profile in the Kustom PortalNothing beyond the order

Ingrid adds order fields such as tos_id. See the Ingrid guide.

Use the Shipping Assistant for options based on the customer’s address or cart, and to reserve shipments in your TMS. Use basic options for a fixed list. With the Shipping Assistant, also send basic options as a fallback if the TMS can’t respond.

You need a TMS that implements the Shipping Assistant API. Most merchants use one of the shipping partners, which already have a connection. Configure carriers, prices and rules in the TMS. Kustom calls the TMS and returns the result on the order; your server doesn’t need to call it.

1. Connect your TMS in the Portal. In the Kustom Portal, add a Shipping Assistant profile for your TMS to your merchant account, with two values from your TMS provider:

  • Identifier — your account’s identifier at the TMS.
  • Key — the secret that goes with it.

A profile applies to the countries you select on it, matched against the customer’s shipping country. A customer shipping to a country no profile covers gets your basic options instead. Production and playground are separate accounts, so set the profile up in each. Changes can take a few minutes to reach the checkout.

2. Send basic options as the fallback. If the TMS is unavailable, too slow or returns an invalid response, Kustom shows the order’s shipping_options. Use the format in Basic shipping options. Without fallback options, the customer can still buy with a delivery address, but the order has no selected_shipping_option.

3. Describe what’s being shipped. To help your TMS price the delivery, optionally add shipping_attributes to each line, and tags to the order for rules that apply to the whole cart:

{
"tags": ["member"],
"order_lines": [
{
"type": "physical",
"reference": "sku-1234",
"name": "Wool sweater",
"quantity": 1,
"unit_price": 79900,
"tax_rate": 2500,
"total_amount": 79900,
"total_tax_amount": 15980,
"shipping_attributes": {
"weight": 890,
"dimensions": { "height": 60, "width": 300, "length": 400 },
"tags": ["fragile"]
}
}
]
}

weight is in grams and dimensions in millimeters. Tags are passed through unchanged, so agree their meaning with your TMS provider.

4. Read the delivery from the order. selected_shipping_option carries more than a basic option does:

FieldWhat it holds
idThe TMS’s id for the option, not one of yours
name, price, tax_amount, tax_rateAs shown to the customer. price includes any time slot, pickup point and add-on surcharge
shipping_methodThe kind of delivery: Home, PickUpPoint, BoxUnreg and so on
delivery_detailscarrier, class, the carrier product and the chosen pickup_location or timeslot
selected_addonsExtras the customer picked, with what they typed, such as a door code
tms_referenceThe shipment your TMS reserved. Book and print labels against this

The shipping_option_change event carries neither the carrier nor tms_reference, so read the order for those.

To skip the TMS for a single order without touching the profile, set options.tms_configuration_override.disabled to true when you create the order. That checkout uses your basic options. It only works on create: setting it on an update has no effect.

Send shipping_options on the order. Kustom shows this list in the checkout.

shipping_options on the order
{
"shipping_options": [
{
"id": "express",
"name": "Express 1–2 days",
"description": "Delivered before 17:00",
"price": 9900,
"tax_amount": 1980,
"tax_rate": 2500,
"shipping_method": "Home",
"preselected": false
},
{
"id": "standard",
"name": "Standard 3–5 days",
"price": 4900,
"tax_amount": 980,
"tax_rate": 2500,
"shipping_method": "PickUpPoint",
"preselected": true
},
{
"id": "store",
"name": "Pick up in store",
"price": 0,
"tax_amount": 0,
"tax_rate": 2500,
"shipping_method": "PickUpStore"
}
]
}

The pane beside this page runs this example. price includes tax; tax_amount is the tax amount, not the rate. To change the list once the checkout is open, for example when the address changes, update the order — see Render the checkout snippet.

  • Basic options: the pane beside this page is a live checkout with the three options above. Pick one and watch the total follow.
  • Shipping Assistant: in playground, open a checkout with a shipping address in a country your profile covers. The delivery step shows your TMS’s options, not your basic list. Complete the purchase, read the order and check selected_shipping_option.tms_reference is set.
  • The fallback: repeat with a customer email containing +fallback, such as jane+fallback@example.com. In playground that skips the TMS, so you see what customers get when it’s unavailable.
You seeWhy
No delivery step at allThe order didn’t ask for one, or the cart had nothing physical
Your basic options instead of the TMS’sNo profile covers the shipping country, the credentials are wrong or the TMS failed. Once a checkout falls back, it stays on your basic options
“We cannot ship to the given address”The TMS returned no options under its rules for that address
“Your shipping option is unavailable” after BuyThe TMS refused the reservation. The customer picks again and retries
An order with no selected_shipping_optionThe checkout fell back and you sent no basic options

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.