Order eSIMs
Places an order for new eSIMs or a top-up and returns the accepted order.
Places an order for new eSIMs or a top-up and returns the accepted order.
Takes the same body as quote and needs the manage order permission (403 / 10003 without it).
An Idempotency-Key header with a new UUID is required for every purchase: a retry with the same key and body
returns the order already accepted, 409 / 12002 with Retry-After while it is still being accepted, and a
changed body gives 409 / 12001.
A top-up is an offer from search?iccid= ordered with inputs.iccid and quantity 1; without
inputs.iccid the same offer is bought as a new eSIM. A new eSIM is instant unless inputs.isInstant
is false, which delivers an entitlement to provision later. Every price is recalculated: a current price above
inputs.maxPrice gives 409 / 11002 before anything is charged. A wallet charge that fails creates no
order and gives 402 / 16000, with details[0] naming wallet and INSUFFICIENT_BALANCE or
WALLET_BLOCKED; send the same request with the same key after a top-up. An unknown or foreign
inputs.iccid gives 404 / 10004 and charges nothing.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
Idempotency-Key*stringUUID idempotency key for safe retries of this operation.
uuid- body
The body B2B eSIM quote and order both take.
currency?|Order currency, three letters in either case; the API key's currency when omitted. An unsupported code gives
400 / 10001 at currency, reason NOT_SUPPORTED, before any item is checked.
referenceId?|Optional partner order reference, unique per partner, at most 128 characters without leading or trailing spaces. A quote validates it and ignores it.
items*array<>1 to 5 items, with at most 5 eSIMs in total.
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/esims/order' \ -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \ -H 'Content-Type: application/json' \ -d '{ "currency": "USD", "referenceId": "partner-order-42", "items": [ { "publicId": "esim_eu_3gb_7d", "quantity": 1, "inputs": { "isInstant": true, "maxPrice": { "amount": 25, "currency": "USD" } } } ]}'{ "id": "01a14329-9cc4-7a1b-9f6e-3c2d1e0b4a58", "referenceId": "partner-order-42", "origin": { "channel": "api" }, "status": "processing", "total": { "amount": 25, "currency": "USD" }, "refunded": { "amount": 0, "currency": "USD" }, "payment": { "status": "completed", "method": "balance", "amount": { "amount": 25, "currency": "USD" }, "wallet": { "label": "Main wallet", "debited": { "amount": 25, "currency": "USD" } }, "failure": null }, "items": [ { "id": "01a14329-9cc4-73a3-8ca6-22a3efdde687", "orderId": "01a14329-9cc4-7a1b-9f6e-3c2d1e0b4a58", "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 mobile networks GET
Lists mobile network codes (MCC/MNC) with their operator, country and calling code. Returns `{ items }` ordered by `mcc` then `mnc`, without paging. Optional filters: `countryCode` (ISO 3166-1 alpha-2, either case) and `mcc` (3 digits); both together return the networks matching both. A malformed filter or an unknown query parameter returns `400` with code `10001`.
eSIM catalog GET
Returns every destination with its plans, page by page, for partner inventory. Returns `{ items, nextCursor }`, in a fixed order, with the search filters except `iccid`. Continue with `nextCursor` as `cursor`, the same filters and the same `currency` until it is null. A cursor reused with other filters or another currency gives 400 / 10001. Quote confirms the final price and availability.