Skip to Content
OpenRoam Docs
Orders

Create an order

Places one order of one to five items, of one or several product types, and pays it from the wallet.

POST
/v1/orders

Places one order of one to five items, of one or several product types, and pays it from the wallet.

Each item names its productType, the publicId of the offer from search or quote, a quantity and, where the product needs them, product-specific inputs (required for hotels and flights). An order has at most five items and a total quantity of at most five; an item with quantity n becomes n separate order items, each with its own items[].id. Every item is validated before anything is charged; a rejected item is reported at items[i] in details, for example 11004 (OFFER_EXPIRED_OR_INVALID) for an unknown, expired or other-product publicId, 11003 (OFFER_UNAVAILABLE) or 11002 (OFFER_PRICE_CHANGED).

The optional maxTotal { amount, currency } caps the whole order: the sum of every item's price times its quantity, in the order currency. Its currency must be the order currency (otherwise 400, 10001, CURRENCY_MISMATCH at maxTotal.currency). A higher total returns 409 with code 11002 (OFFER_PRICE_CHANGED) at maxTotal, after every item is priced and before anything is charged; a total equal to it is accepted.

The order total is charged to the partner's selected wallet. On success the order is processing and its items start as pending; delivery continues after the response, so follow it with GET orders/{id}, GET orders/{orderId}/fulfillment/status or the order.fulfillment.updated webhook. If the charge fails, no order is created and the call returns 402 with code 16000 (PAYMENT_FAILED); when the reason is known, details[0] names wallet with reason INSUFFICIENT_BALANCE or WALLET_BLOCKED. Top up or unblock the wallet and send the same request again with the same Idempotency-Key.

Requires an Idempotency-Key header (a UUID) per purchase. Repeating the same request with the same key never charges twice: once the order is accepted it returns 200 with that order's current state; while the first request is still running it returns 409 with code 12002 (IDEMPOTENCY_KEY_IN_PROGRESS) and a Retry-After header, after which you send the same request again; a different body with the same key returns 409 with code 12001 (IDEMPOTENCY_KEY_REQUEST_MISMATCH). After a timeout or 5xx, retry with the same key and body rather than a new key. A referenceId already used by another order of the partner returns 409 with code 10005 (CONFLICT). An eSIM top-up whose inputs.iccid is not one of your eSIMs returns 404 with code 10004 (NOT_FOUND) and charges nothing.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Header Parameters

Idempotency-Key*string

UUID idempotency key for safe retries of this operation.

Formatuuid

Request Body

The order to place.

  1. body

An order of one to five items, of one or several product types, paid from the wallet.

items*array<|||||>

Required. One to five items; the sum of their quantity is at most five.

currency?|

Three-letter currency code the order is priced and charged in, for example USD. When omitted or empty, the API key's default currency is used. An unsupported code gives 400 / 10001 at currency, reason NOT_SUPPORTED, before any item is checked.

referenceId?|

Optional reference of your own, up to 128 characters, without leading or trailing whitespace. It must be unique among your orders (a reused value returns 409) and can be used to find the order with the referenceId filter of the order list.

maxTotal?|

Optional highest accepted order total, in the order currency: the sum of every item's price times its quantity. A higher total gives 409 / 11002 at maxTotal before anything is charged; a currency other than the order currency gives 400 / 10001 at maxTotal.currency.

Response Body

OK

  1. response

The current state of an order.

id*string

Order id.

Formatuuid
origin*

Where the order was created.

status*string

Current order status: paymentPending, processing, completed, partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.

Value in"paymentPending""processing""completed""partiallyFulfilled""fulfillmentFailed""partiallyRefunded""refunded""cancelled"
total*

What was charged for the order, in the order's currency, before refunds: the item prices plus completed amendment charges, less completed amendment credits.

refunded*

What completed item refunds returned, in the order's currency; zero when nothing was returned. You paid total minus refunded, the sum of the items' effectivePaidAmount.

payment?|

The latest payment attempt; null when none was made.

items*array<|||||>

The order items, one per unit bought.

timeline*array<>

Every status the order has had, oldest first, each once per stretch.

createdAt*string

When the order was created (UTC).

Formatdate-time
updatedAt*string

When anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.

Formatdate-time
fulfillmentVersion*integer

Increases with every fulfillment change; matches the order.fulfillment.updated webhook.

Formatint64
referenceId?|

Your own order reference, when one was sent.

customer?|

The traveller who paid on your hosted site, masked; null unless the origin is site, and once the traveller's details are deleted at the end of their retention period.

Example Request
curl -X POST 'https://api.sandbox.openroam.com/v1/orders' \  -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \  -H 'Content-Type: application/json' \  -d '{  "currency": "USD",  "referenceId": "trip-42",  "maxTotal": {    "amount": 50,    "currency": "USD"  },  "items": [    {      "productType": "airtime",      "publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm",      "quantity": 1,      "inputs": {        "phoneNumber": "+994501234567"      }    },    {      "productType": "esim",      "publicId": "esim_eu_3gb_7d",      "quantity": 1,      "inputs": {        "isInstant": true      }    }  ]}'
Example Response
{  "id": "01a14340-7a10-7c55-a1f2-9b3d5e7f0a11",  "referenceId": "trip-42",  "origin": {    "channel": "api"  },  "status": "processing",  "total": {    "amount": 50,    "currency": "USD"  },  "refunded": {    "amount": 0,    "currency": "USD"  },  "payment": {    "status": "completed",    "method": "balance",    "amount": {      "amount": 50,      "currency": "USD"    },    "wallet": {      "label": "Main wallet",      "debited": {        "amount": 50,        "currency": "USD"      }    },    "failure": null  },  "items": [    {      "id": "01a14340-7a2b-7d10-8e4c-2b6f9a1c3d50",      "orderId": "01a14340-7a10-7c55-a1f2-9b3d5e7f0a11",      "productType": "airtime",      "price": {        "amount": 25,        "currency": "USD"      },      "purchasedProduct": {        "name": "Test operator 40 AZN",        "countryCode": "AZ",        "logoUrl": "https://cdn.openroam.test/airtime/test-operator.png",        "value": {          "amount": 40,          "currency": "AZN"        },        "inputs": {          "phoneNumber": "+994***4567",          "minDeliveredValue": null        },        "details": {          "redemptionType": "directTopUp",          "estimatedDeliveredValue": {            "amount": 40,            "currency": "AZN"          },          "readMore": "Credit arrives within minutes."        }      },      "fulfillment": {        "status": "pending",        "result": null,        "failure": null      },      "actions": {        "amendment": {          "availability": "notAvailable",          "reason": null        },        "cancellation": {          "availability": "notAvailable",          "reason": null        },        "update": {          "availability": "notAvailable",          "reason": null        }      },      "createdAt": "2026-10-16T05:27:59.521962Z",      "effectivePaidAmount": {        "amount": 25,        "currency": "USD"      }    },    {      "id": "01a14340-7a2b-7e21-9f5d-3c7a0b2d4e61",      "orderId": "01a14340-7a10-7c55-a1f2-9b3d5e7f0a11",      "productType": "esim",      "price": {        "amount": 25,        "currency": "USD"      },      "purchasedProduct": {        "name": "Europe 3 GB 7 days",        "countryCode": null,        "logoUrl": "https://cdn.openroam.test/esims/europe.png",        "inputs": {          "eid": null,          "imei2": null,          "iccid": null,          "travelStartDate": null,          "isInstant": true        },        "details": {          "orderType": "esim",          "isInstant": true,          "destination": {            "id": "destn_k3m7q2t5w4y6b2d4f6h3j5n7pq",            "name": "Europe",            "code": "EU"          }        }      },      "fulfillment": {        "status": "pending",        "result": null,        "failure": null      },      "actions": {        "amendment": {          "availability": "notAvailable",          "reason": null        },        "cancellation": {          "availability": "notAvailable",          "reason": null        },        "update": {          "availability": "notAvailable",          "reason": null        }      },      "createdAt": "2026-10-16T05:27:59.521962Z",      "effectivePaidAmount": {        "amount": 25,        "currency": "USD"      }    }  ],  "timeline": [    {      "status": "paymentPending",      "occurredAt": "2026-10-16T05:27:59.521962Z"    },    {      "status": "processing",      "occurredAt": "2026-10-16T05:27:59.521962Z"    }  ],  "createdAt": "2026-10-16T05:27:59.521962Z",  "updatedAt": "2026-10-16T05:27:59.521962Z",  "fulfillmentVersion": 1}

List account services GET

Lists every service OpenRoam sells through the Partner API, with whether the account may sell it. Returns `{ services }`, one entry per service, ordered by `productType`, without paging. Each entry is `{ productType, enabled, requestable }`. `enabled` is `true` when the account may search, quote and order the service now; any other request that sells it returns `403` with code `10003`. `requestable` is `true` when the account can ask OpenRoam to enable the service; an enabled service is never requestable. A service OpenRoam does not offer at the moment is not listed. The endpoint takes no query parameters; an unknown parameter returns `400` with code `10001`.

List orders GET

Lists the partner's orders, newest first, with optional filters. Returns `{ orders, pagination }`. Each summary has `id`, `referenceId`, `origin`, `status`, `total`, the latest `payment` and `itemCount`; read one order for its items and timeline. Orders created through the API, the dashboard and the partner's sites are all listed; `channel` (`api`, `dashboard` or `site`, the values of `origin.channel`) keeps one of them. With a site credential, only the orders of that site are listed. `orderStatuses` takes the values of `status` and matches the status the order reads now. Filters combine with AND; repeated `productTypes` or `orderStatuses` values combine with OR. A `productTypes` filter selects orders containing at least one item of that type and still returns the whole order. Filters apply before counting and paging, so send the same filters on every page. Use flat `page` (default 1) and `limit` (default 10, 1 to 100) query parameters. `cursor`, `skip`, `offset`, nested paging keys and repeated paging parameters return `400` with code `10001` (`INVALID_REQUEST`).