Copy page

Documentation

Orders

An order is the first state-changing commerce step. It rechecks the quote, price and stock, debits the wallet once and creates a purchase with child orders. The whole request is atomic: a failure creates no purchase and no debit.

Code
POST /v1/orders
Idempotency-Key: order-2026-001

Required scope: orders:write. The account must have completed review (onboardingStatus: active); otherwise the API returns 403 account_not_active.

Two request shapes

Quote-based

Code
{
  "reference": "booking-123",
  "quoteId": "22222222-2222-4222-8222-222222222222"
}

One-call

Code
{
  "reference": "booking-124",
  "currency": "USD",
  "expectedTotalMinor": 1618,
  "items": [
    { "offerId": "11111111-1111-4111-8111-111111111111", "quantity": 2 }
  ]
}

The one-call shape creates an internal quote, compares expectedTotalMinor with the fresh total and then purchases. It does not skip the quote; it hides the extra round trip. If the total differs, the API returns 409 price_changed with the new totalMinor and the fresh quote, and does not charge.

expectedTotalMinor is optional. Use it for any autonomous caller so a price move cannot silently exceed the mandate.

Rules

A successful order consumes the quote and changes its status to accepted.

Response

Code
{
  "purchaseId": "33333333-3333-4333-8333-333333333333",
  "status": "processing",
  "amountMinor": 1618,
  "currency": "USD",
  "orderIds": ["44444444-4444-4444-8444-444444444444"],
  "balanceAfterMinor": 8382
}

A processing status means at least one unit is awaiting upstream fulfilment. The wallet is already debited. Poll GET /v1/orders/{purchaseId} until the status is terminal.

Status model

Code
processing ──> completed
     │
     └────────> failed

completed      all child orders fulfilled
processing     at least one child order is paid or awaiting fulfilment
failed         at least one child order is fulfillment_failed or replaced
partially_fulfilled  target contract, not live
cancelled      target contract, no cancel endpoint live

Child order statuses are paid, fulfilled, fulfillment_failed, cancelled and refunded. A purchase status is derived from its children. partially_fulfilled is part of the target contract but is not returned by the current service.

Read orders

Code
GET /v1/orders
GET /v1/orders/{purchaseId}

GET /v1/orders returns the latest 50 purchase operations for the partner. GET /v1/orders/{purchaseId} returns the purchase and its child orders. Both require orders:read and share the order-read limit.

The response currently includes a child order store field for internal compatibility. Do not display, store or rely on it. The public contract is that upstream store and product identifiers are not exposed; treat any internal field as non-contractual and report it if it appears in a customer-facing surface. This documentation does not reproduce its values.

Delivery timing

GET /v1/delivery measures completed deliveries over the last 30 days. The clock starts at payment, or at order creation for wallet orders, and stops when the eSIM is issued and attached to a fulfilled order. The response reports sampleSize, medianMs, p90Ms, under10sPercent, fastestMs and slowestMs. A small sample stays a small sample; do not turn it into a public claim without enough volume.

GET /v1/orders/{purchaseId} also returns a delivery object with status, startedAt, completedAt and durationMs for that purchase.

Redemption

Code
POST /v1/orders/{purchaseId}/redeem
Idempotency-Key: redeem-2026-001

Code
{ "format": "both" }

Maximum 20 eSIMs per batch. A retry with the same idempotency key returns the same fixed batch, not the next 20. The response contains batchId, format, items (orderItemId, esimCodeId, iccid, lpa) and qrSvgs when requested.

Code
{
  "batchId": "55555555-5555-4555-8555-555555555555",
  "format": "both",
  "items": [
    {
      "orderItemId": "66666666-6666-4666-8666-666666666666",
      "esimCodeId": "77777777-7777-4777-8777-777777777777",
      "iccid": "8985...REDACTED",
      "lpa": "LPA:1$REDACTED"
    }
  ],
  "qrSvgs": ["<svg>REDACTED</svg>"]
}

GET /v1/orders/{purchaseId}/redeem is Planned. Use the POST form.

Payment failures

The current service returns 402 insufficient_funds when available wallet credit is below the total. The target contract adds 402 payment_required with a funding_url and an approval_required state for orders above a threshold. Neither new shape is live in every deployment yet. Handle both if present, and never ask an agent for card details.

Errors

Related

• Quotes for the pricing step.
• Wallet for the debit source.
• Webhooks for order.completed and order.processing.
• Approval flow for threshold decisions.