Skip to content
Docs
Get playground access

Create the order

POST your order to /checkout/v3/orders, store the order_id the 201 hands back, read the order back and reuse it when the customer returns to the checkout.

Starting playground session…
  1. Build the payload
  2. Create order
  3. Render snippet
  4. Validate · optional
  5. Confirm & push

On this page you'll

  • Authenticate against the Playground and production with the right credentials
  • POST an order and get back an order_id and an html_snippet
  • Read an order back from /checkout/v3/orders/{order_id}
POST
/checkout/v3/orders
Line 1 quantity2
curl -X POST 'https://api.playground.kustom.co/checkout/v3/orders' \
  -u "$KUSTOM_MERCHANT_ID:$KUSTOM_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
  "purchase_country": "SE",
  "purchase_currency": "SEK",
  "locale": "en-SE",
  "order_amount": 108000,
  "order_tax_amount": 21600,
  "order_lines": [
    {
      "type": "physical",
      "reference": "tshirt-001",
      "name": "Cotton T-Shirt",
      "quantity": 2,
      "quantity_unit": "pcs",
      "unit_price": 25000,
      "tax_rate": 2500,
      "total_amount": 50000,
      "total_discount_amount": 0,
      "total_tax_amount": 10000
    },
    {
      "type": "physical",
      "reference": "chinos-001",
      "name": "Slim Fit Chinos",
      "quantity": 1,
      "quantity_unit": "pcs",
      "unit_price": 70000,
      "tax_rate": 2500,
      "total_amount": 70000,
      "total_discount_amount": 0,
      "total_tax_amount": 14000
    },
    {
      "type": "discount",
      "reference": "discount-10pct",
      "name": "10% off",
      "quantity": 1,
      "quantity_unit": "pcs",
      "unit_price": -12000,
      "tax_rate": 2500,
      "total_amount": -12000,
      "total_discount_amount": 0,
      "total_tax_amount": -2400
    }
  ],
  "options": {
    "allow_separate_shipping_address": true
  }
}'

The docs proxy injects your session's credentials. In your own code, use your Playground API username and API password.

You have an order payload — see What to send if you don’t yet. POST it to /checkout/v3/orders and a 201 hands back two things you’ll keep: an order_id and an html_snippet. This page is that call, what each of the two is for and reading the order back — changing one that already exists belongs to the next page, once there’s a rendered checkout to keep in sync.

Authenticate

Section titled “Authenticate”

Every call to the Checkout API uses HTTP Basic auth with your API username and API password, both created in the Kustom Portal. Authentication and environments covers getting them.

Authorization: Basic base64(<API username>:<API password>)
EnvironmentBase URL
Playgroundhttps://api.playground.kustom.co
Productionhttps://api.kustom.co

Credentials are environment-specific — a Playground merchant ID doesn’t authenticate against production, or the reverse. Authentication and environments covers getting a key and rotating one.

Send the request

Section titled “Send the request”

POST the payload to /checkout/v3/orders. A 201 comes back with two things worth naming, because the rest of this guide is built on them:

FieldWhere it livesWhat it’s for
order_idResponse bodyIdentifies the order — in every later read and update, and in Order Management later
html_snippetResponse bodyThe markup Render Checkout snippet puts on your page

Anything that fails here is a payload problem, not a request one — see What to send for the amount identities Kustom checks before it accepts anything.

Store the order_id

Section titled “Store the order_id”

Store order_id on the cart. Every later read and update of this order is keyed on it, at {base URL}/checkout/v3/orders/{order_id} — the one URL you’ll build for the rest of the integration.

The 201 also carries a Location header, and it holds no more than the order_id already does: it’s that same URL, {base URL}/checkout/v3/orders/{order_id}, already absolute. Build the URL from order_id and you never need to read it.

Read it back

Section titled “Read it back”

GET the order at {base URL}/checkout/v3/orders/{order_id} and you get the order exactly as Kustom holds it — the fields you sent, plus whatever the customer has added since.

GET
/checkout/v3/orders/{order_id}
Create an order above first
curl -X GET 'https://api.playground.kustom.co/checkout/v3/orders/{order_id}' \
  -u "$KUSTOM_MERCHANT_ID:$KUSTOM_SECRET" \
  -H 'Content-Type: application/json'

The docs proxy injects your session's credentials. In your own code, use your Playground API username and API password.

This is a read. Changing an order you’ve already created, while a customer is looking at it, is Render Checkout snippet’s job, not this page’s.

When the customer comes back

Section titled “When the customer comes back”

Customers close tabs and walk back to product pages. Create a fresh order every time they return and you throw away everything they had already typed into the checkout.

Keep the stored order_id with the session, and on re-entry:

  1. Look for a stored order_id before creating anything.
  2. If there is one, GET the order. You get it back with its html_snippet, and can update it instead of creating a new one.
  3. If that GET returns a 4xx, a 5xx or anything else unexpected, create a new order.

The fallback in step 3 isn’t optional: an order expires after 48 hours without activity, and can expire sooner. A cart change while the customer is on the page is an update to the same order, never a second one — Render Checkout snippet has the sequence.

When it breaks

Section titled “When it breaks”

An order is valid for 48 hours after the last merchant update or customer interaction, then expires, and a GET against its URL answers 404 with an empty body — create a new order rather than trying to resurrect the old one.

A failed create isn’t safe to retry blindly either: POST /checkout/v3/orders carries no idempotency key, so retrying an ambiguous 5xx can leave you with two orders instead of one. See Troubleshooting Checkout for the full error catalogue, Idempotency and retries for the calls that do carry a key and Limits for the rate this call counts against.

Prove it

Section titled “Prove it”

The editor at the top of this page is wired to the Playground, not a mock — edit a field, hit Run, and you get back a real order_id and a real html_snippet, the same two things a production call returns.

That html_snippet isn’t on a page yet, and updating this order only means something once it is — both are Render Checkout snippet’s job.

Section titled “Related”

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