Create an order
Places one order of one to five items, of one or several product types, and pays it from the wallet.
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.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
Idempotency-Key*stringUUID idempotency key for safe retries of this operation.
uuidThe order to place.
- 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.
OK
- response
The current state of an order.
id*stringOrder id.
uuidorigin*Where the order was created.
status*stringCurrent order status: paymentPending, processing, completed,
partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.
"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*stringWhen the order was created (UTC).
date-timeupdatedAt*stringWhen anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.
date-timefulfillmentVersion*integerIncreases with every fulfillment change; matches the
order.fulfillment.updated webhook.
int64referenceId?|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.
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 } } ]}'{ "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`).