Timeouts, fallback and testing your TMS

Your TMS sits in the middle of someone’s purchase, so Kustom is built to keep the checkout working when your TMS doesn’t. That makes failures quiet: a broken POST /shippingoptions doesn’t show the customer an error, it swaps your options for the merchant’s own. This page lists what each failure does, the time limits, and how to test against playground before a merchant goes live.

What each failure does

What happens	What the customer sees
POST /shippingoptions times out, answers anything but 200, or returns a body Kustom can’t use	The merchant’s fallback options. For the rest of that checkout: Kustom stops calling you for it
POST /auth fails, or a call still gets 401 after a fresh token	Same as above
POST /shippingoptions returns an empty list	“We cannot ship to the given address”. Not a fallback: the customer changes the address, and Kustom asks again
POST /shipment or PUT /shipment/{shipment_id} fails in any way	The purchase stops, Kustom asks for options again and the customer picks again. See Refusing a reservation
That new POST /shippingoptions fails too	The merchant’s fallback options
POST /shipment/{shipment_id}/confirm fails	Nothing. The purchase is already complete

Fallback is a checkout with no TMS at all. The customer chooses from the fixed list the merchant put on the order, and if the merchant sent no list, buys with a delivery address and no delivery option. Either way, no reservation reaches you for that purchase, so the merchant has to book it some other way. Every fallback is a lost booking for you and extra work for them.

“A body Kustom can’t use” is broader than malformed JSON. One unknown value anywhere rejects the whole response — the list is on the options page. Validate your own responses against it before you go live.

Time limits

Kustom gives each call 8 seconds by default, and less for some integrations. Past that, the call has failed. A customer is watching a spinner while POST /shippingoptions runs, so aim for well under a second there. POST /shipment runs while they wait after pressing Buy, so the same goes for it.

Kustom repeats a call once, a second later, after some network errors. That’s why the same POST /shipment can arrive twice — see Make POST /shipment safe to repeat.

If a large share of calls to your host fail in a short time, Kustom stops calling it for a few seconds, and every checkout in that window falls back. A slow dependency that makes some calls time out can take down calls that would have succeeded.

Test in playground

Kustom’s playground environment is separate from production, with its own merchant accounts. Build against it first.

1. Try your endpoints in Shipwreck, Kustom’s test tool for TMS integrations. It calls your API the way the checkout does and shows how your options render in the shipping selector.
2. Connect a playground merchant. A playground merchant account adds a Shipping Assistant profile pointing at your TMS, with an identifier and key you issue — see Shipping options in the checkout. No playground merchant to test with? Create one with Get playground access at the top of this page, or at portal.playground.kustom.co.
3. Walk through a real checkout. Enter an address, change it, search for a pickup point, press Buy, and complete the purchase. Check that each call from the flow reaches you and that your shipment_id arrives on the order as tms_reference.
4. Test the failures. Answer 401 once and watch Kustom re-authenticate. Refuse a reservation with a failure_reason. Make PUT /shipment/{shipment_id} answer 404.
5. Check the merchant’s fallback. A customer email containing +fallback, such as jane+fallback@example.com, makes playground skip your TMS and show the fallback options, so the merchant can see what their customers get when you’re unavailable.

Before you go live

• Every response validates against the lists on the options page, for every carrier and type you’ll return.
• POST /shipment returns the same shipment_id when it’s repeated for a session_id.
• PUT /shipment/{shipment_id} replaces the reservation rather than adding one.
• POST /shippingoptions answers inside a second under your expected load.
• Each merchant has their own Identifier and Key, and you can revoke one without the others.
• You log Klarna-Correlation-Id, so Kustom support can find a call you’re asking about.

Related

• Build a TMS integration — the flow and what you must build
• Shipping options in the checkout — what the merchant’s fallback list looks like
• Shipping Service Callback API