- Checkout
- Features
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.
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
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.
What both share
Section titled “What both share”- Enable delivery. Set
options.allow_separate_shipping_addresstotrue, or send a non-emptyshipping_optionslist, when you create the order. A list containing only an option withshipping_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_changeclient-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.
Who adds the shipping fee
Section titled “Who adds the shipping fee”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_feeline, a zero-amount one for a free option, and raisesorder_amountandorder_tax_amountto match. Don’t add it yourself or the fee is counted twice. - You add it, through a callback. Register
merchant_urls.shipping_option_updateand 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.
Which to use
Section titled “Which to use”| Shipping Assistant | Basic shipping options | |
|---|---|---|
| Options come from | Your TMS, asked live | A fixed list on the order |
| Address and cart updates | Kustom requests new options from the TMS | Your integration updates the list on the order |
| Pickup points on a map, time slots, add-ons | Yes | No |
| Shipment reserved in your TMS | Yes, its id arrives as tms_reference | No |
| What you set up | A TMS and a profile in the Kustom Portal | Nothing 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.
Shipping Assistant
Section titled “Shipping Assistant”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:
| Field | What it holds |
|---|---|
id | The TMS’s id for the option, not one of yours |
name, price, tax_amount, tax_rate | As shown to the customer. price includes any time slot, pickup point and add-on surcharge |
shipping_method | The kind of delivery: Home, PickUpPoint, BoxUnreg and so on |
delivery_details | carrier, class, the carrier product and the chosen pickup_location or timeslot |
selected_addons | Extras the customer picked, with what they typed, such as a door code |
tms_reference | The 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.
Basic shipping options
Section titled “Basic shipping options”Send shipping_options on the order. Kustom shows this list in the checkout.
{ "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.
Check it works
Section titled “Check it works”- 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_referenceis set. - The fallback: repeat with a customer email containing
+fallback, such asjane+fallback@example.com. In playground that skips the TMS, so you see what customers get when it’s unavailable.
Troubleshooting
Section titled “Troubleshooting”| You see | Why |
|---|---|
| No delivery step at all | The order didn’t ask for one, or the cart had nothing physical |
| Your basic options instead of the TMS’s | No 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 Buy | The TMS refused the reservation. The customer picks again and retries |
An order with no selected_shipping_option | The checkout fell back and you sent no basic options |
Related
Section titled “Related”- Shipping partners — the TMS providers with a connection, and what each needs in the Portal
- Build a TMS integration — implement the TMS endpoints Kustom calls
- Ingrid
This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.