Skip to content

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.

CallbackFires whenYou answer with
address_updateThe customer enters or edits an addressA corrected cart, a shipping options list or both
country_changeThe customer switches purchase countryThe same, plus the new purchase_currency and locale
shipping_option_updateThe customer picks a shipping option inside the iframeA corrected cart
validationJust before the purchase completes200 to allow, 303 to deny
upsell, upsell_validation, upsell_notificationThe confirmation page offers add-onsRecommendations, then an approval
pushAbout two minutes after the purchase completes200, then fetch and acknowledge the order
notificationA pending order’s status resolves200

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.

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 be https with 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 — 4900 is 49.00 — and tax_rate carries two implicit decimals, so 25% is 2500. 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_change or shipping_option_update stops the purchase. For validation, it allows the purchase by default.
  • Anything other than 200 from address_update, country_change or shipping_option_update stops 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 deliberate 400 or 3xx, described per callback below. validation has its own rules.
  • Don’t GET or PUT the 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.

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_amount and order_lines, recalculated for the new address.
  • A shipping options list — shipping_options, holding the options valid for this address, with one marked preselected.
  • Nothing. A 200 with an empty JSON object, {}, means nothing changes. A 200 with 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.

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.

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.

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, 302 or 307 with a Location header — deny it, and send the customer to a page of yours that explains why.
  • 400 with an error_type of address_error or approval_failed, plus error_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 other error_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 Other
Location: https://shop.example/cart?unavailable=SWEATER-M

Full field list: Order validation. Handle callbacks explains how to choose between fail-open and fail-closed validation.

Three URLs belong to the confirmation-page upsell feature rather than to the checkout session:

  • upsell is called to fetch the recommendations to show.
  • upsell_validation is called before the upsell lines are added to the completed order.
  • upsell_notification is 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/json

Then acknowledge it, which tells Kustom you have the order and ends the retry schedule.

POST /ordermanagement/v1/orders/{order_id}/acknowledge
Authorization: Basic <base64 of username:password>
Content-Type: application/json

Kustom 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.

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.

  • 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 200 you sent was ignored. A cart is applied only when order_amount, order_tax_amount and order_lines are all three present — two of them is no update at all. Other parts of the body, shipping_options and purchase_currency among 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_update in 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.

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