Skip to main content

Create checkout

POST 
/api/v1/carts

Creates a checkout (cart): one referenceId holding multiple shop positions, purchased together. Unlike POST /orders (1 referenceId = 1 order), a checkout fans out to N orders created atomically under a single reference. /orders is unchanged.

v1 is shop-only — ordersType must be "shop"; dtu / esim are rejected with HTTP 422.

All-or-nothing​

A single out-of-stock or invalid line fails the entire cart: nothing is charged and zero orders are created (HTTP 4xx). There is no partial-success path at creation.

Idempotency​

referenceId is REQUIRED and is both the cart id and the idempotency key (unique within your account). Replaying the same referenceId returns the original aggregate with statusCode=IDEMPOTENCY_REPLAY (refreshed from the live orders), without creating a second cart -- even if the body differs.

Spend cap (HTTP 409)​

The API key's static transactionLimit is checked against the cart total (the summed quote). If it cannot accommodate the cart, the response is HTTP 409 / statusCode=API_KEY_LIMIT_EXCEEDED (errorCode="api_key_transaction_limit_exceeded") and the message names the attempted cart total. NOT a rate limit -- raise the cap.

Async (HTTP 202)​

If any position is accepted for asynchronous processing (e.g. a long order), the aggregate status is IN_PROGRESS, the endpoint returns HTTP 202 with a Retry-After: 15 header, and statusCode=ACCEPTED.

Rate limit (HTTP 429)​

Because one checkout fans out to N orders in a single call, it has its own rate-limit bucket (POST /carts), scoped per API-key user — distinct from the purchase branch of POST /orders (checkOnly=false), which has no per-window bucket. DTU pre-checks use their own POST /orders (check) bucket. On excess the response is HTTP 429 / statusCode=LIMIT_REACHED with a Retry-After header and the bucket name in the message. The bucket's limit/window default to the global rate-limit defaults and are tuned per environment via a rate_limit_rules row; the effective value is visible in GET /api/v1/rate-limits. This is a true rate limit (retry after the window) — distinct from the HTTP 409 spend cap above.

Retrieval, polling & voucher codes​

Poll and retrieve the created orders via GET /orders?referenceId=<your referenceId>. Voucher codes are revealed per order with GET /orders?referenceId=...&unhide=true (or by orderId); the checkout response itself never returns codes.

Requires the orders:write scope.

Request​

Responses​

Successful Response