Build a TMS integration

The Kustom Shipping Assistant (KSA) puts live delivery choices inside Kustom Checkout: carriers, pickup points on a map, delivery times, time slots and extras such as a door code or an SMS notification. None of it is stored at Kustom. Each time the customer’s address or cart changes, Kustom asks the merchant’s transport management system (TMS) what it can offer, and when the customer buys, Kustom reserves the chosen delivery with that same system. This guide is for the team that builds the TMS side of those calls.

Are you a merchant who wants the Shipping Assistant in your checkout? You don’t build any of this. Your TMS provider does, or already has. Shipping options in the checkout covers what you do: a profile in the Kustom Portal and a couple of fields on the order.

Everything below is for the TMS: a transport management system, a transport administrator or a merchant building a direct integration. You implement a small HTTP API that Kustom calls. You never call Kustom, and you don’t need to know the Checkout API to do it.

How your TMS fits into a checkout

This is the happy path: a customer enters an address, picks a delivery and pays on the first try. Each numbered step is a moment in their checkout, the arrows are the calls it causes, and each step links to the page that covers it.

Play the sequence

CustomerKustomYour TMS

1. 1Customer enters an address
   Kustom → Your TMS

   POST

   /authOnly without a valid token

   Your TMS → Kustomtoken

   Kustom → Your TMS

   POST

   /shippingoptions

   Your TMS → Kustomoptions

   Kustom → Customershows the options
2. 2Customer presses Buy
   Kustom → Your TMS

   POST

   /shipment

   Your TMS → Kustomshipment_id
3. 3Purchase completes
   Kustom → Your TMS

   POST

   /shipment/{shipment_id}/confirm

What the happy path leaves out:

• POST /auth comes first only when needed. Kustom calls it right before its first call to your TMS, and whenever you answer 401. The token is kept per merchant profile and reused across checkouts, so most checkouts never call /auth at all.
• Options are asked for more than once. Kustom asks again when the address or the cart changes, and the first request can carry only a country, before the customer has typed anything.
• Pressing Buy is not a purchase. The payment can still be declined. The customer may then change the address, the cart or the delivery and press Buy again, and Kustom updates the reservation it already has with PUT instead of creating a second one. A reservation may be updated several times, or never confirmed at all.
• Customers can search for pickup points near another postal code, which is another POST /shippingoptions.
• You can refuse a reservation. The customer is asked to pick again.
• A failed answer to POST /shippingoptions shows the customer no error. The checkout quietly switches to the merchant’s own fixed list of options, and stays on it for that customer.

What you must build

Kustom calls one base URL for each merchant profile and appends the paths below to it. There is no separate URL for authentication.

Endpoint	You must build it?	Kustom calls it when	Without it
POST /auth	Yes	Right before a call to your TMS when Kustom has no token for the merchant profile, and after you answer 401	Nothing else can be called. Every checkout falls back to the merchant’s options
POST /shippingoptions	Yes	The address or cart changes, and on a pickup-point search	Every checkout falls back to the merchant’s options
POST /shipment	Yes	The customer presses Buy for the first time	Every purchase is interrupted
PUT /shipment/{shipment_id}	Yes, or answer 404	The customer presses Buy again after a reservation exists	Answer 404 and Kustom creates a new reservation with POST /shipment, leaving the first one orphaned in your system
POST /shipment/{shipment_id}/confirm	No	The purchase completes	Reservations in your system are never confirmed. The purchase still goes through

The API reference also lists GET /shipment/{shipment_id}. Kustom doesn’t call it, so you don’t need to build it.

Inside each response, some fields are required and some are optional with a sensible default. The page for each call lists them, and marks the fields that are optional on paper but required for a usable result, such as pickup locations on a pickup-point option.

Words this guide uses

Term	What it means here
Checkout session	One customer’s visit to one merchant’s checkout. session_id in every request identifies it, and stays the same through retries and changes
Order lines	The items in the cart. Only physical goods are sent to you
Fallback options	A fixed list of delivery options the merchant puts on the order, used when your TMS can’t answer
Preview options	Options you return before the full address is known, marked preview: true. The customer sees them but can’t buy with one
shipment_id	Your identifier for a reservation. The merchant receives it as tms_reference on their order, and books against it
Minor units	Amounts in the currency’s smallest unit, tax included. 4900 is 49.00

Related

• Shipping options in the checkout — the merchant’s side, and the fixed list used as the fallback
• Shipping Service Callback API — the generated reference for all six operations
• Shipping partners — the TMS providers that already have a connection