Skip to Content
OpenRoam Docs
eSIMs

Quote eSIMs

Prices the order body with current prices, without placing an order.

POST
/v1/esims/quote

Prices the order body with current prices, without placing an order.

Takes the same body as order and, as the order does, checks each item completely (its inputs, its publicId and its price) before the next one, in request order. The first failure aborts the quote, and an item error is named at items[i], for example 409 / 11002 at items[i].inputs.maxPrice when the current price is above it. An eSIM has no monetary value, so inputs.value is an unknown member (400 / 10001). An unknown or foreign inputs.iccid gives 404 / 10004. A quote reserves nothing and does not expire.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Request Body

  1. 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.

Response Body

OK

  1. response

Current prices for the requested items, in request order. total is the sum of each item's unit price times its quantity. A quote reserves nothing and does not expire.

currency*string
items*array<>
total*
Example Request
curl -X POST 'https://api.sandbox.openroam.com/v1/esims/quote' \  -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"        }      }    }  ]}'
Example Response
{  "currency": "USD",  "items": [    {      "publicId": "esim_eu_3gb_7d",      "quantity": 1,      "name": "Europe 3 GB 7 days",      "price": {        "amount": 25,        "currency": "USD"      }    }  ],  "total": {    "amount": 25,    "currency": "USD"  }}

Provision a deferred eSIM POST

Provisions a deferred eSIM bought with `inputs.isInstant: false` and returns it. Creates the eSIM for an order item that delivered an entitlement, and returns it as `GET /esims/{iccid}` does. The item's result moves to `provisioning.status` `processing` and then `ready`, and each change sends an `order.fulfillment.updated` webhook. An `Idempotency-Key` header with a UUID is required: a retry with the same key and body after the call finished returns the eSIM as it reads now and starts nothing again, 409 / 12002 with `Retry-After` while the call is still running, and a changed body gives 409 / 12001. The optional body `{ travelStartDate }` is needed when the plan requires the first day of travel and the order did not send it (400 / 10001 without it); a date other than the one recorded, or a new date once provisioning has started, gives 409 / 10005. An instant eSIM gives 400 / 10001, and an ID that names no eSIM purchase of yours, such as a top-up item, gives 404 / 10004.

Search eSIM plans GET

Searches eSIM destinations and returns them with their plans, one page at a time. Returns `{ items, pagination }`. `countryCode` keeps the destinations whose coverage includes that country, so local, regional and global destinations can match; `category` and `region` select destinations, and `validityDays` and `isUnlimited` select plans within them. Pages count destinations with an orderable plan. With `iccid` it returns the plans that can top up that eSIM instead, under its destination, and takes no filter other than `currency` (400 / 10001, `NOT_ALLOWED`); an unknown or foreign ICCID gives 404 / 10004. Prices are indicative, in `currency`.