Orders

An order turns a priced item into delivered digital goods, paid from your prefunded wallet. Creation is asynchronous and idempotent; the status lifecycle below is the contract to build against. Creating orders requires orders.create; reading them, their history and their reveal allowance requires orders.read.

Create an order

POST /api/v1/orders
Idempotency-Key: <your unique key, 1–128 printable characters>

Name what to buy in exactly one of two ways.

The item itself — priced and ordered in one call:

{
  "clientReference": "your-order-1001",
  "item": {
    "productId": "0198d72d-99d6-75a6-9f12-971050ba7a5f",
    "variantId": "0198d72d-a15b-7cbf-ab69-b95410e98636",
    "value": null,
    "quantity": 1,
    "currency": "USD"
  },
  "maximumTotal": 55.00
}

A quote you created with POST /quotes:

{
  "quoteId": "0198d72d-a6ce-77c6-9586-fc36708731d0",
  "clientReference": "your-order-1001",
  "purchaseInput": { "phoneNumber": "+15551234567" }
}

The body takes no other members: a misspelt or unknown member — maximumTotl, item.valu, a workspaceId — is refused with 400 invalid_request and named in the problem's errors map, and nothing is ordered.

A successful create returns 202 Accepted with a Location header (/api/v1/orders/{orderId}) and the order body in state reserved — your wallet has reserved the order's total, and fulfillment proceeds in the background (typically seconds).

Idempotency — the retry contract

The Idempotency-Key header is mandatory. Its guarantee: for a given key, an order is placed at most once. Send the same key again — after a timeout, a crash, a network error, or a 5xx — and you get the same order back, never a duplicate purchase.

• The key space is your workspace's. Every API key of the workspace shares it: a key string one of your services spent cannot be reused by another.
• A spent key is spent for good. The key is recorded with the order it placed and never expires; a new purchase needs a new key.
• A replay answers 202 Accepted with the order as it stands now — it may already be fulfilled. Nothing is priced, reserved or charged again.
• With quoteId, a retry is the same request when it names the same quote, the same clientReference and the same purchaseInput. Anything else under a spent key is 409 idempotency_conflict.
• With item, a retry is judged by the request it repeats, as it was sent — never by today's catalog: the same productId, variantId, value (or the same absence of one; 25 and 25.00 are one amount), quantity, currency (any letter case), clientReference (surrounding spaces ignored) and purchaseInput. It must also accept the order's total: a retry whose maximumTotal is below the total the key's order was placed at is a different request. Anything else — naming the amount the original left out, or the reverse, included — is 409 idempotency_conflict.
• When the key's order kept no record of the request it was sent with, an item retry is judged from the order itself instead: it is the same purchase when the order has exactly one line, of the same productId and variantId, the same quantity, the same settlement currency, the same clientReference and the same purchaseInput, for the amount the retry names (an omitted value being the product's default face value, as a fresh quote would read it) — and the order's total is still within the retry's maximumTotal. Two kinds of order have no such record: one placed before Xegora began recording the request with the key, and one placed from a quoteId (a quote is not an item request, so there is nothing to record). A genuine retry of either is therefore answered with the order it already placed, not refused.
• A quoteId request never answers for an item order. A one-call purchase makes a quote of its own, so a spent key can never be presented with the same quoteId again: send item to retry an item order.
• A refused request does not spend the key. price_above_maximum, insufficient_funds, an unavailable product or any other refusal places nothing: correct the request and send it again under the same key.

Rules of thumb: derive the key from your own order identity (e.g. order-{yourOrderId}), not from a random value per attempt — randomness defeats the whole point — and keep it stable across process restarts (persist it with your order row).

Why an order is refused

Nothing is reserved by a refused request, and its key is not spent.

GET /api/v1/workspace shows the limits your orders are held to, currency by currency, with what the last 30 days already count (limits[].rolling30DayOrdersUsed) and whether a currency is blocked for want of limits.

The status lifecycle

status is a string, always lowercase on the wire; treat unknown future values as non-terminal and keep polling. These are the statuses an API order takes:

The status vocabulary also names pending, cancelled and refundpending, which an API order does not take: an order is created reserved (its history starts with a pending entry at the same instant), it is never cancelled — an order that is not delivered is failed — and its refunds complete in one step. Treat them as you would any status you do not recognize.

reserved → processing → fulfilled → refunded
reserved → fulfilled                                 (delivered at the first attempt)
reserved | processing → failed                       (not delivered; reservation released)
reserved | processing → refunded                     (refunded before delivery; reservation released)
reserved | processing → reconciliationrequired → processing | fulfilled | failed | refunded

A phone top-up's recipient number

purchaseInput.phoneNumber is checked for form when the order is placed — a number that is not E.164 is refused on the spot with 422 purchase_input_invalid, and nothing is reserved. Whether that number can actually receive the top-up is a different question, and one only the network behind the product can answer, so Xegora asks it while fulfilling the order, before any money is spent. A number the product cannot reach ends the order at failed on its first fulfillment attempt, with the whole reservation released and a statusReason saying which way it was wrong:

Both are ordinary failed outcomes: the reservation is released in full, nothing is charged, and the Idempotency-Key that placed the order is spent (the order exists), so a corrected order is a new order under a new key. Products other than phone-top-up never carry these reasons.

Read an order

GET /api/v1/orders/{orderId}

Returns the order or 404 (code: "not_found") — including for orders that belong to another workspace, which are indistinguishable from nonexistent ones by design.

{
  "id": "0198e000-1111-7abc-9def-222233334444",
  "clientReference": "your-order-1001",
  "status": "fulfilled",
  "total": 58.50,
  "currency": "USD",
  "createdAtUtc": "2026-09-05T12:01:02+00:00",
  "updatedAtUtc": "2026-09-05T12:01:09+00:00",
  "lines": [
    {
      "productName": "Game Store Gift Card",
      "variantLabel": "50",
      "quantity": 1,
      "unitPrice": 58.50,
      "currency": "USD",
      "faceValue": 50.00,
      "faceCurrency": "EUR",
      "requestedValue": null,
      "productId": "0198d5c0-90aa-7d3e-8f10-3c5f60b1a222",
      "variantId": "0198d5c0-91bb-7e4f-9a21-4d6e70c2b333",
      "lineTotal": 58.50
    }
  ],
  "publicReference": "ord_0198e00011117abc9def222233334444",
  "completedAtUtc": "2026-09-05T12:01:09+00:00",
  "statusReason": null,
  "refund": null
}

An order carries two kinds of amount, and they are never the same number: total in currency is the settlement — what was reserved and debited from your wallet, in your sell currency — while each line's faceValue in faceCurrency is the denomination the buyer receives (the 50 EUR card above, paid for with 58.50 USD). faceValue is null when the item is not money (a data plan, a bundle).

The money on a line — unitPrice, lineTotal, faceValue, requestedValue — is frozen at order time from the quote that priced the order, so a receipt built from the order can never drift from what you were quoted, and you do not need to keep the quote around. productName and variantLabel are frozen with it: a line shows the product and option names as they were recorded when the order was placed, so a later rename in the catalog never rewrites what you sold. These are the same names webhooks, notifications and the invoice carry, so an order read here and an order.fulfilled event always say the same thing. (Only the oldest orders, placed before names were recorded on the line, fall back to the catalog's current name. A quote is the other way round: it stores no names, so GET /quotes/{quoteId} always reads today's catalog — see Quotes.) Reconcile by productId and variantId all the same.

Read an order's history

GET /api/v1/orders/{orderId}/history

The order's tracking timeline: every status it moved through, oldest first. 404 for an order that does not exist or is another workspace's.

[
  { "status": "pending", "previousStatus": null, "changedAtUtc": "2026-09-05T12:01:02+00:00", "reason": null },
  { "status": "reserved", "previousStatus": "pending", "changedAtUtc": "2026-09-05T12:01:02+00:00", "reason": null },
  { "status": "reconciliationrequired", "previousStatus": "reserved", "changedAtUtc": "2026-09-05T12:31:40+00:00", "reason": "outcome_unconfirmed" },
  { "status": "fulfilled", "previousStatus": "reconciliationrequired", "changedAtUtc": "2026-09-05T14:05:12+00:00", "reason": null }
]

status and previousStatus use the order's status vocabulary; reason is one of the statusReason values, or null when no reason you may read was recorded. An entry whose status equals its previousStatus is an annotation: the status did not change, but a reason was recorded (for example refund_under_review on a delivered order). Who made a change is never part of the history.

List orders

GET /api/v1/orders?offset=0&limit=50&status=fulfilled
GET /api/v1/orders?clientReference=your-order-1001
GET /api/v1/orders?updatedFrom=2026-09-05T12:00:00Z

Newest-first by creation time, offset-paginated. Every filter is optional and they combine:

Response: { items, offset, limit, hasMore }; when hasMore is true, request offset + items.length. Timestamps are ISO 8601 instants — use Z, or URL-encode the + of an offset as %2B.

The list is your reconciliation backbone: a periodic sweep with updatedFrom set to your last sweep's start catches anything a missed webhook or crashed worker left behind.

Tracking progress: webhooks first, polling as backup

• Webhooks push order.processing, order.under_review, order.fulfilled, order.failed, and order.refunded to your endpoint within moments — see Webhooks.
• Polling: GET /orders/{id} every 3–6 seconds is fine while an order is in flight (well within the rate limit for reasonable volumes); back off once you rely on webhooks.

Never mark an order delivered in your system from anything but a fulfilled status you read from the API or a verified order.fulfilled webhook.