- Checkout
- API reference
Server-side callbacks
Handle Kustom Checkout callbacks for address, country and shipping changes, validation and completed orders. Includes requests, responses and examples.
Kustom calls your server during checkout to update prices and shipping options or validate
the purchase, and after purchase to notify you about the order. Register each callback URL in
merchant_urls on the order. The sections below describe each callback’s response and failure
behavior.
| Callback | Fires when | You answer with |
|---|---|---|
address_update | The customer enters or edits an address | A corrected cart, a shipping options list or both |
country_change | The customer switches purchase country | The same, plus the new purchase_currency and locale |
shipping_option_update | The customer picks a shipping option inside the iframe | A corrected cart |
validation | Just before the purchase completes | 200 to allow, 303 to deny |
upsell, upsell_validation, upsell_notification | The confirmation page offers add-ons | Recommendations, then an approval |
push | About two minutes after the purchase completes | 200, then fetch and acknowledge the order |
notification | A pending order’s status resolves | 200 |
shipping_address_update is an older name for address_update.
terms, checkout, confirmation and cancellation_terms are browser destinations.
Kustom doesn’t POST to them. See Checkout URLs and callbacks.
How every callback works
Section titled “How every callback works”Register callback URLs together on the order:
{ "merchant_urls": { "terms": "https://shop.example/terms", "checkout": "https://shop.example/checkout?kustom_order_id={checkout.order.id}", "confirmation": "https://shop.example/confirmation?kustom_order_id={checkout.order.id}", "push": "https://shop.example/api/kustom/push?kustom_order_id={checkout.order.id}", "address_update": "https://shop.example/api/kustom/address-update", "country_change": "https://shop.example/api/kustom/country-change", "shipping_option_update": "https://shop.example/api/kustom/shipping-option", "validation": "https://shop.example/api/kustom/validate", "notification": "https://shop.example/api/kustom/notification?kustom_order_id={checkout.order.id}" }}Callback requirements:
POST, JSON, HTTPS. Every callback URL must behttpswith a real certificate. A self-signed certificate may survive the in-session callbacks and will fail the push.{checkout.order.id}is substituted into the URL before it’s called, so a handler can read the order id from its own query string.- Amounts are minor units —
4900is 49.00 — andtax_ratecarries two implicit decimals, so 25% is2500. The identities Kustom validates are on Order lines and tax. - In-session callbacks have ten seconds to respond. Later responses are discarded.
A timeout on
address_update,country_changeorshipping_option_updatestops the purchase. Forvalidation, it allows the purchase by default. - Anything other than
200fromaddress_update,country_changeorshipping_option_updatestops the purchase. The customer is shown a generic error and told to try again, and the failure is logged for merchant support. The one exception is a deliberate400or3xx, described per callback below.validationhas its own rules. - Don’t
GETorPUTthe order inside an in-session handler. The response body is the update. A separate write can conflict with it. - Developer Logs in the Playground Portal lists every callback Kustom made for an order and the status code you returned. Search by order id to inspect the response.
address_update
Section titled “address_update”What it does. Reprices the cart for a destination. Kustom POSTs the current cart and
addresses, then applies the fields in your response.
When it fires. Whenever the customer enters or edits the billing or shipping address. If the customer only enters one address, it serves as both.
Use it when tax, shipping prices or available options depend on the address.
What you get. order_amount, order_tax_amount, order_lines, billing_address,
shipping_address, selected_shipping_option, purchase_currency and customer, plus
locale, merchant_data, merchant_reference1, merchant_reference2 and tags when the
order has them.
What you answer with. A 200 carrying any of:
- A cart —
order_amount,order_tax_amountandorder_lines, recalculated for the new address. - A shipping options list —
shipping_options, holding the options valid for this address, with one markedpreselected. - Nothing. A
200with an empty JSON object,{}, means nothing changes. A200with no body at all is not valid JSON and fails like any other bad response.
Send order_amount, order_tax_amount and order_lines together; if any is missing, the
cart update is ignored. shipping_options, purchase_currency, locale and merchant_data
each apply independently.
To reject the address instead, answer 400 with an error_type of address_error,
unsupported_shipping_address or approval_failed. The first and last also require
error_text, which is shown to the customer, who stays in the checkout and can correct it. A
303 with a Location header sends them out to a page of yours instead.
Example. A customer changes their shipping address from Stockholm to a remote postal code in northern Sweden. Remove same-day delivery and apply the carrier’s surcharge:
// Kustom sends{ "order_amount": 84800, "order_tax_amount": 16960, "order_lines": [ /* … */ ], "shipping_address": { "postal_code": "981 31", "city": "Kiruna", "country": "SE" }}// You answer 200{ "order_amount": 88800, "order_tax_amount": 17760, "purchase_currency": "SEK", "order_lines": [ /* … the shipping_fee line now 8900 */ ], "shipping_options": [ { "id": "standard", "name": "Standard 3–5 days", "price": 8900, "tax_amount": 1780, "tax_rate": 2500, "preselected": true } ]}Full field list: Address update.
shipping_address_update is the older name for this callback. Kustom uses it only when
address_update is absent. Both have the same trigger, request and response. Set only one;
use address_update for new integrations.
country_change
Section titled “country_change”What it does. Updates prices, currency and locale for a new country.
When it fires. When the customer switches the billing or shipping country. It takes the same
request and the same response shape, so most of address_update above applies unchanged.
Use it when you sell into more than one market. You must handle it if an order allows several shipping countries, so currency and language match the selected country.
What you answer with. Include purchase_currency and locale with the cart. Use your
prices for the new market; Kustom charges the amounts you send.
Example. A customer switches from Sweden to Finland.
// You answer 200{ "purchase_currency": "EUR", "locale": "fi-FI", "order_amount": 7500, "order_tax_amount": 1524, "order_lines": [ /* … priced in EUR, tax_rate 2550 for FI … */ ]}Full field list: Country change. Sell in multiple markets covers the rest of the multi-market setup.
shipping_option_update
Section titled “shipping_option_update”What it does. Lets you set the shipping fee when the customer changes their shipping option.
Without this callback, Kustom adds a shipping_fee line using the selected option’s name,
price and tax. With merchant_urls.shipping_option_update registered, Kustom sets
selected_shipping_option and calls you instead. Your response must include the
shipping_fee line; if you omit it, the order has no shipping line.
When it fires. When the customer picks a different shipping option inside the checkout iframe. If your own page owns shipping selection, Kustom already handles the cost update and you don’t need this callback at all.
Use it when shipping discounts, free-shipping thresholds or cart-dependent surcharges change the option’s listed price.
Example. The cart contains a 799.00 SEK sweater and the code SAVE50, which discounts
goods and halves shipping. The customer switches from Standard to Express at 49.00. Add a
shipping_fee line with the 50% discount and recalculate the totals:
// Kustom sends{ "order_amount": 79900, "order_tax_amount": 15980, "selected_shipping_option": { "id": "express", "name": "Express 1–2 days", "price": 4900, "tax_amount": 980, "tax_rate": 2500 }, "order_lines": [ { "reference": "SWEATER-M", "name": "Wool sweater", "quantity": 1, "unit_price": 79900, "tax_rate": 2500, "total_amount": 79900, "total_discount_amount": 0, "total_tax_amount": 15980 } ]}// You answer 200 — SAVE50 halves the fee{ "order_amount": 82350, "order_tax_amount": 16470, "purchase_currency": "SEK", "order_lines": [ { "reference": "SWEATER-M", "name": "Wool sweater", "quantity": 1, "unit_price": 79900, "tax_rate": 2500, "total_amount": 79900, "total_discount_amount": 0, "total_tax_amount": 15980 }, { "type": "shipping_fee", "reference": "express", "name": "Express 1–2 days (SAVE50)", "quantity": 1, "unit_price": 4900, "tax_rate": 2500, "total_amount": 2450, "total_discount_amount": 2450, "total_tax_amount": 490 } ]}Use total_discount_amount to show the discount separately from unit_price. Kustom rejects
a response if line amounts don’t reconcile with quantities, prices and discounts, or if
order_amount doesn’t match the sum of the lines. See
Order lines and tax.
Full field list: Shipping option update. Shipping options covers how to supply the options.
validation
Section titled “validation”What it does. Lets you check the order and assign your own order number before purchase.
Kustom POSTs the whole order while its status is checkout_incomplete.
When it fires. After the customer presses Pay order and before the payment is authorized.
Use it when stock, prices, delivery restrictions or fraud checks can change before purchase. Checkout orders remain valid for 48 hours after the last merchant update or customer interaction.
What you answer with.
200— allow the purchase. The customer is redirected to confirmation as usual.303,301,302or307with aLocationheader — deny it, and send the customer to a page of yours that explains why.400with anerror_typeofaddress_errororapproval_failed, pluserror_text— deny it, but keep the customer in the checkout and show them the message. These are the only two accepted types. Kustom logs and ignores any othererror_type, and the purchase completes.
It fails open. Validation must answer within ten seconds. If it doesn’t, Kustom treats the
order as valid and redirects to confirmation anyway. If you want to require a successful
response, set
options.require_validate_callback_success
to true on the order.
Example. The last medium sweater sold while the customer was entering their address.
HTTP/1.1 303 See OtherLocation: https://shop.example/cart?unavailable=SWEATER-MFull field list: Order validation. Handle callbacks explains how to choose between fail-open and fail-closed validation.
upsell
Section titled “upsell”Three URLs belong to the confirmation-page upsell feature rather than to the checkout session:
upsellis called to fetch the recommendations to show.upsell_validationis called before the upsell lines are added to the completed order.upsell_notificationis called after the upsell lines have been added.
Upsell must be enabled for your account before any of them is called.
See Upsell on the confirmation page for setup and Upsell callback reference for request and response fields.
What it does. Notifies your server of a completed purchase, even if the customer doesn’t reach your confirmation page.
When it fires. After the purchase completes and the order has been queued into Order Management. Expect roughly a two-minute delay before the first attempt.
Use it always. It’s one of the two required notifications, and the only one that doesn’t depend on a browser.
What you answer with. Answer 200 straight away. The push only tells you that an order
completed. It doesn’t carry the order, so read the order id from the query string and fetch the
order, import it into your system and acknowledge it. Confirmation &
push walks through all three steps.
GET /ordermanagement/v1/orders/{order_id}Authorization: Basic <base64 of username:password>Content-Type: application/jsonThen acknowledge it, which tells Kustom you have the order and ends the retry schedule.
POST /ordermanagement/v1/orders/{order_id}/acknowledgeAuthorization: Basic <base64 of username:password>Content-Type: application/jsonKustom retries the push at 5, 15, 30 and 60 minutes, then every four hours, for a total of 48 hours or until you acknowledge. After 48 hours it stops regardless.
You can also write your references onto the order when you acknowledge it.
merchant_reference1 is the customer-facing order id your shop generated. merchant_reference2
is free for a second identifier of your own.
The push and confirmation redirect can each arrive alone or first. Both are equally authoritative. If the order doesn’t exist in your system when the push arrives, create it. If you’ve decided not to fulfill it, cancel it in Kustom rather than ignoring it. Confirm the order has the browser-side half and the idempotency this implies.
notification
Section titled “notification”What it does. Notifies you when a pending order’s status changes.
When it fires. When the status of a pending order changes. An order comes back with
fraud_status of ACCEPTED, PENDING or REJECTED. A PENDING order is one Kustom is still
reviewing, and this callback is how you hear the outcome.
Use it when any of your payment methods can leave an order pending. It isn’t called for orders that resolve immediately.
What you answer with. 200. As with the push, treat it as a notification rather than a
payload: put {checkout.order.id} in the URL, then fetch the order from Order Management and
read its current fraud_status. Don’t release goods on a PENDING order.
Troubleshooting
Section titled “Troubleshooting”- The purchase stops with a generic error message. An in-session callback returned a status
other than
200, returned an invalid cart or shipping option list, or didn’t answer within ten seconds. Check Developer Logs for the response you actually sent. - The cart in a
200you sent was ignored. A cart is applied only whenorder_amount,order_tax_amountandorder_linesare all three present — two of them is no update at all. Other parts of the body,shipping_optionsandpurchase_currencyamong them, apply independently of it and of each other. - The purchase completes before validation responds. Validation must complete within ten seconds. Past that, Kustom treats the order as valid and redirects to confirmation.
- The push never arrives. The push requires a publicly reachable HTTPS endpoint with a valid
certificate. A self-signed certificate that worked for
address_updatein testing won’t work here. - Pushes keep arriving for an order you already have. You’re not acknowledging it. Acknowledge on the confirmation page as well as from the push handler.
- A 4xx or 5xx from the Checkout API mid-session. Create a new order. Checkout orders are only valid for 48 hours after the last merchant update or customer interaction, and expire after that. See Troubleshooting Checkout.
Related
Section titled “Related”- Handle callbacks — decide which of these you need and whether validation should fail open or closed.
- Checkout URLs and callbacks — the whole
merchant_urlsobject, browser destinations included. - Order lines and tax — build a cart response that passes validation.
- Confirm the order — the browser-side half of the push.
- Sell in multiple markets — configure
country_change. - Checkout JavaScript events — the browser-side events, so your own cart panel stays in sync with the iframe.
- Capture an order — capture payment when you ship the goods.
- Checkout Callback API — the generated reference for all six in-session and upsell operations.
This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.