Skip to content
Docs
Get playground access

What an order is

The one object every Kustom product shares — how amounts are written, why order lines must add up, what the two html_snippets are for and which fields the order carries from cart to refund.

An order is the cart as Kustom sees it, and it’s the only object you ever really work with. Checkout creates it, the customer pays it, Order Management captures and refunds it, Finance settles it. The integration models differ in where the customer sees the order. The object is the same throughout, so the rules below hold in every tab of these docs.

What it carries

Section titled “What it carries”

The fields group into four jobs. Everything else on the object is a detail of one of them, and each job has one rule that bites.

Where, and in what money
purchase_country purchase_currency locale
Must match a market on your merchant account. SE / SEK / en-SE always works in the Playground.
What is being bought
order_lines[] order_amount order_tax_amount
Every amount is in minor units — 25000 is 250.00 SEK — and the line totals must sum to the order totals exactly.
Where Kustom calls you
merchant_urls.terms .checkout .confirmation .push .validation
Every URL Kustom calls — confirmation, push, validation — must be HTTPS. The first four are required, while validation and the shipping endpoints are not. The push URL is how you learn the order was placed even if the customer’s browser never reaches your confirmation page.
Who, and how
billing_address shipping_address customer options merchant_reference1/2 merchant_data
Mostly filled in by the customer, not by you. Your own references are how you find the order again in your systems.

The two snippets

Section titled “The two snippets”

An order carries HTML twice, and both are yours to render.

  1. After you create it, the response includes an html_snippet. Put it on your checkout page and its script loads the checkout iframe the customer pays in.
  2. After the customer pays, reading the order back returns a second html_snippet — now a receipt — for your confirmation page.

Neither snippet is a URL you construct. Take them from the order as returned. The order’s own URL you do build, from the order_id you stored: /checkout/v3/orders/{order_id}.

Why the totals are strict

Section titled “Why the totals are strict”

Kustom doesn’t correct a cart. It refuses one. order_amount must equal the sum of every line’s total_amount, and order_tax_amount the sum of every total_tax_amount, to the minor unit. The reason is that the amount the customer sees, authorizes and is eventually charged must be the same number all the way through, and a rounded line is the usual way they drift apart. Compute line totals as quantity × unit_price − total_discount_amount, derive tax from that and sum — the live editor in the quickstart checks this before it sends. A tiny rounding difference is tolerated rather than rejected, but it exists to absorb the last minor unit of an awkward tax rate, not to license rounding: compute the totals and there is nothing for it to absorb.

One object, wherever it’s paid

Section titled “One object, wherever it’s paid”

The same order is what a Checkout iframe, a Hosted Payment Page, Elements and an in-store terminal all operate on. Choosing between them is a decision about rendering, not about the API — Integration models compares them.

Section titled “Related”

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