- Checkout
- Get started
Confirm the order
Handle Kustom Checkout confirmation and push callbacks, read and acknowledge orders idempotently and recover completed orders after missed callbacks.
On this page you'll
- Build a confirmation route and a push handler that do the same work, idempotently
- Compare order status case-insensitively and read the order instead of trusting the query string
- Acknowledge from both routes, and sweep Order Management for the rare order whose push never arrives
After validation, Kustom reports a completed purchase through a browser redirect and a server-to-server push. Handle both: either can arrive without the other.
- The customer presses Pay orderThe customer
In the checkout, once they have picked a payment method. Nothing for you to build here.
- The payment goes throughKustom
Kustom authorizes the payment with the customer's payment method, and the order's status becomes checkout_complete. The order is read-only from here.
- Kustom redirects the browser to your confirmation pageKustom
A GET to merchant_urls.confirmation, with the order id in the query string. Your route reads the order, records it, acknowledges it and shows the receipt.
If the customer closes the tab before the redirect lands, this never arrives.
- About two minutes later, the pushKustom
A POST to merchant_urls.push, server-to-server, whether or not the redirect arrived. Your handler does the same recording, so it has to be harmless the second time.
Kustom retries it at 5, 15, 30 and 60 minutes, then every four hours, until you acknowledge the order or 48 hours pass. It can also arrive before the redirect.
The push in full →
Why neither path is optional
Section titled “Why neither path is optional”| Path | How it arrives | When |
|---|---|---|
| Browser redirect | GET to merchant_urls.confirmation, {checkout.order.id} substituted in | Right after the customer presses Pay order |
| Server-to-server push | POST to merchant_urls.push | Usually about two minutes later, whether or not the browser got there. It can also arrive first |
If the customer closes the tab, switches to a banking app or loses their connection, the redirect may never reach you. The push lets you record the order without the browser.
Both routes must be idempotent for each order_id. Pushes retry until you acknowledge
the order, and customers can reload confirmation. Repeated calls must not create duplicate records.
Build both routes
Section titled “Build both routes”Both URLs carry the order id in a query parameter you name when you register them —
order_id here:
"confirmation": "https://shop.example/confirmation?order_id={checkout.order.id}","push": "https://shop.example/push?order_id={checkout.order.id}"Each route verifies the purchase, then calls the same function to record and acknowledge it.
// merchant_urls.confirmation -- the browser redirect. May never arrive.app.get('/confirmation', async (req, res) => { const order = await readFromKustom(`/checkout/v3/orders/${req.query.order_id}`); // The API returns this in lowercase; the OpenAPI document's example is uppercase. if (String(order?.status).toLowerCase() !== 'checkout_complete') { return res.redirect('/checkout'); // not paid: no receipt, nothing recorded } await recordAndAcknowledge(order.order_id); res.send(`<div id="confirmation">${order.html_snippet}</div>`);});
// merchant_urls.push -- server-to-server, usually about two minutes later. Independent of the redirect.app.post('/push', async (req, res) => { res.sendStatus(200); // answer first, then do the work // Order Management holds an order only once the purchase has completed. const order = await readFromKustom(`/ordermanagement/v1/orders/${req.query.order_id}`); if (order) await recordAndAcknowledge(order.order_id);});
// A GET to Kustom. null for a 404, so "no such order" is an answer rather than an exception.async function readFromKustom(path) { const r = await fetch(`${KUSTOM}${path}`, { headers: { Authorization: auth } }); if (r.status === 404) return null; if (!r.ok) throw new Error(`${path} answered ${r.status}`); return r.json();}
// Safe to call from any route, any number of times, for the same order.async function recordAndAcknowledge(orderId) { await db.orders.upsert({ id: orderId, confirmed: true }); // keyed on order_id await fetch(`${KUSTOM}/ordermanagement/v1/orders/${orderId}/acknowledge`, { method: 'POST', headers: { Authorization: auth }, });}The confirmation route reads the Checkout API for the receipt snippet. The push handler reads Order Management, where the order remains available after it expires from the Checkout API. This example relies on push retries if acknowledgement fails.
After completion, html_snippet shows a receipt. Render it with the same script handling as
the checkout snippet; innerHTML alone doesn’t execute scripts. See
Put it on the page.
The confirmation snippet is available for 2 hours. The confirmation html_snippet loads for two hours after the order is completed. The order
itself stays readable through the Checkout API for 48 hours, so a reload after that point
still returns the order even though the snippet no longer loads.
Fit the order into your own fields
Section titled “Fit the order into your own fields”When extending recordAndAcknowledge to store order details, adapt values to your system’s
field limits before saving them.
- Address lines. For a line longer than your limit with an empty second line, look for a
whole-word unit designator and split there:
APT,BSMT,BLDG,DEPT,FL,FRNT,HNGR,LBBY,LOT,LOWR,OFC,PH,PIER,REAR,RM,SIDE,SLIP,SPC,STOP,STE,TRLR,UNIT,UPPR. Truncate afterwards if it’s still too long. - Names. Truncate the first name at 15 characters and the last name at 100, and strip
@ $ ! % ^ & * ( ) ~ + #and angle brackets from the first name — then apply the same validation to the last name. - Phone numbers arrive in E.164 format: a plus sign, country code, then the subscriber number including area code, up to fifteen digits.
- US postal codes come in both five-digit and five-plus-four forms. Accept both.
When it breaks
Section titled “When it breaks”| Symptom | What’s happening |
|---|---|
Your status check never matches checkout_complete | The API returns it in lowercase, but the OpenAPI document’s example shows it uppercase. Compare case-insensitively |
| The confirmation page renders a blank checkout | The snippet needs the same <script> re-execution as the checkout page. See Put it on the page |
| A cancelled or stale order confirms successfully | The route trusted order_id from the query string instead of reading the order and checking its own status |
| Pushes keep arriving for an order you already have | You aren’t acknowledging it. Acknowledge from both routes — see Server-side callbacks |
Recover orders whose push never arrives
Section titled “Recover orders whose push never arrives”Push retries continue for 48 hours. A wrong URL or a longer outage can leave completed orders unrecorded. Periodically check unconfirmed orders in your system:
- List the orders your own system still shows short of confirmed, created more than an hour ago — long enough that the redirect and the first pushes have had their chance.
GETeach one from Order Management —GET /ordermanagement/v1/orders/{order_id}, the same read the push handler makes. A404means the purchase never completed, and there’s nothing to record.- Call
recordAndAcknowledgefor each completed order.
Use Order Management for this check. The Checkout API returns 404 after its 48-hour
read window, even for completed purchases.
The shared recordAndAcknowledge function upserts by order_id, so a concurrent push or
confirmation reload won’t create a duplicate.
Prove it
Section titled “Prove it”Complete a purchase using Playground test data. The docs’ confirmation page reads and acknowledges the order; both calls and their response statuses appear above. The docs’ push endpoint also answers the callback, but that call isn’t shown here. Use Developer Logs to inspect pushes in your integration.
Use the same order_id to capture the order when ready.
Next: Run the end-to-end test cases.
Related
Section titled “Related”- Server-side callbacks — every callback’s payload, response shape and the push retry schedule in full.
- Order lifecycle — every status an order moves through, including
checkout_complete. - Checkout URLs and callbacks — where
confirmationandpushare registered. - Capture an order — move the money once the goods ship.
- End-to-end test cases — the launch checks this guide has been building toward.
This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.