eSIMs
Sell data eSIM plans for a country, a region or the world, deliver the install details, and manage the eSIM after purchase.
What you can sell
OpenRoam sells data eSIM plans by destination. A destination is one country (local), a region such as Europe (regional) or the whole world (global). Each destination lists offers: plans with a data allowance, a validity in days and a price.
You can sell:
- A new eSIM. Installed at once (the default) or as a deferred entitlement that you provision later.
- A top-up. An extra plan added to an eSIM you already bought, addressed by its ICCID.
An eSIM has no monetary value, so there is no inputs.value on this product. The price guard is inputs.maxPrice.
The flow
Search
GET /v1/esims/search returns destinations with their offers, one page at a time. Filter by countryCode, category, region, validityDays, isUnlimited and currency. A country filter matches the destination's coverage, so countryCode=FR returns France and every regional or global destination that covers France.
Other ways to browse:
GET /v1/esims/destinationslists every destination with an orderable offer, as summaries without offers.GET /v1/esims/destinations/{id}returns one destination in the shape search returns.GET /v1/esims/catalogwalks every destination page by page with a cursor. Continue withnextCursor, the same filters and the same currency untilnextCursoris null.GET /v1/esims/compatible-deviceslists devices that support eSIM.
Unknown query parameters are rejected with 400 / 10001 (UNSUPPORTED_FIELD).
Quote
POST /v1/esims/quote prices an order body. It has no side effects: nothing is charged or reserved, and a quote does not expire or bind the order. To hold a quoted price, send it as inputs.maxPrice in the order.
Order
POST /v1/esims/order takes the same body as the quote. It needs an Idempotency-Key header and an API key with the manage permission. The response is the shared order envelope, read later with GET /v1/orders/{id}. See Idempotency and Orders.
You can also buy eSIMs together with other products through POST /v1/orders, where each item adds productType: "esim".
Destinations and offers
A destination looks like this (shortened):
{
"id": "destn_k3m7q2t5w4y6b2d4f6h3j5n7pq",
"name": "Europe",
"countryCode": null,
"category": "regional",
"logoUrl": "https://example.com/esims/europe.png",
"description": null,
"offers": [
{
"publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
"name": "Europe 3 GB 7 days",
"description": null,
"price": { "amount": 25.00, "currency": "USD" },
"requiredInputs": [
{
"name": "isInstant",
"type": "boolean",
"required": false,
"description": "Defaults to true, which creates the eSIM when the order is fulfilled. False delivers an entitlement, and the eSIM is created later through provisioning."
}
],
"details": {
"validityDays": 7,
"data": { "amount": 3072, "unit": "MB", "isUnlimited": false, "label": "3 GB" },
"voice": null,
"sms": null,
"apn": { "apn": "internet", "apnUsername": null, "apnPassword": null },
"properties": { "withTopUp": true, "withHotspot": true, "activation": "first-use", "charge": "one-time" },
"restrictions": { "throttle": false, "throttleSpeed": null, "expireInDays": 30 },
"notes": [ "Data only. Calls and SMS are not included." ],
"plan": null
}
}
],
"details": {
"destinationCode": "EU",
"region": "Europe",
"coverage": [
{ "countryCode": "FR", "name": "France", "networks": [ "4G", "5G" ], "carriers": [ "Example Mobile" ] }
]
}
}Things to know:
idis the destination id.publicIdon an offer is the id you quote and order with. Treat both as opaque. A destination id is never orderable; sent as apublicIdit gives400 / 11004.countryCodeis an ISO 3166-1 alpha-2 code for a local destination and null for a regional or global one.details.destinationCodeis the destination's own code, such asFR,EUorNAM.priceis indicative. The quote is authoritative.details.data.amountis in MB. It is null whenisUnlimitedis true or the amount is not known.details.properties.withTopUptells you whether the plan can be topped up.- After a purchase,
GET /v1/esims/destinations/{id}with the order item'spurchasedProduct.details.destination.idreturns the coverage of the destination the eSIM was bought for.
Required inputs
Each offer lists the inputs it takes in requiredInputs:
name | type | Required | Listed on |
|---|---|---|---|
eid | text | yes | Offers that require the device EID. |
imei2 | text | yes | Offers that require the device's second IMEI. |
travelStartDate | date | yes | Offers that require the first day of travel (YYYY-MM-DD). A deferred purchase may send it at provisioning instead. |
isInstant | boolean | no | Every purchase offer. true (the default) creates the eSIM when the order is fulfilled. false delivers an entitlement. |
iccid | text | yes | Top-up offers only. See Top-ups. |
A new eSIM without an input its offer lists as required fails with 400 / 10001, reason REQUIRED, at items[i].inputs.<name>, before anything is charged. eid and imei2 are needed for a deferred purchase too, because provisioning reuses the values the order recorded. travelStartDate is needed on an instant purchase only.
inputs also takes the standard maxPrice field (below). requiredInputs never lists it. inputs may be omitted for an offer that needs none.
Quote and order
Quote and order take the same body:
{
"currency": "USD",
"referenceId": "partner-order-42",
"items": [
{
"publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
"quantity": 1,
"inputs": {
"isInstant": true,
"maxPrice": { "amount": 25, "currency": "USD" }
}
}
]
}curl -X POST https://api.sandbox.openroam.com/v1/esims/quote \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d @esim-order.json
curl -X POST https://api.sandbox.openroam.com/v1/esims/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @esim-order.jsonThe quote response:
{
"currency": "USD",
"items": [
{
"publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
"quantity": 1,
"name": "Europe 3 GB 7 days",
"price": { "amount": 25.00, "currency": "USD" }
}
],
"total": { "amount": 25.00, "currency": "USD" }
}Rules:
- 1 to 5 items, and at most 5 eSIMs in total. A new eSIM accepts a
quantityabove 1, and each eSIM becomes its own order item. A top-up takesquantity1. referenceIdis your own reference. Quote validates it and ignores it.inputs.valuedoes not exist for eSIM. Sending it, or sendingvalueormaxPricebesideinputs, fails with400 / 10001and reasonINVALID_VALUE.inputs.maxPriceis{ amount, currency }, the highest unit price you accept, in the order currency. A current price above it fails with409 / 11002(PRICE_CHANGED) atitems[i].inputs.maxPrice, and nothing is charged. A different currency gives400 / 10001(CURRENCY_MISMATCH). The amount must be above 0 and use no more decimals than its currency.- Items are checked one at a time in request order. The first failing item ends the request, and quote and order report the same error for it.
Top-ups
A top-up adds a plan to an eSIM you already bought.
- Call
GET /v1/esims/search?iccid=<iccid>. It returns the eSIM's own destination with the offers that can top it up. Each offer lists onlyiccidinrequiredInputs. The result is empty when no plan can top the eSIM up. Withiccid, every filter other thancurrencyis rejected (NOT_ALLOWED). - Quote and order that offer with
inputs.iccid. Read the ICCID from the purchase'sfulfillment.result.details.iccid.
{
"currency": "USD",
"items": [
{ "publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p", "quantity": 1, "inputs": { "iccid": "8944501234567890123" } }
]
}inputs.iccid is what makes an item a top-up. A top-up offer has the same publicId as the plan sold as a new eSIM. The same item without inputs.iccid is quoted and ordered as a new eSIM, and no error reports the missing ICCID. Always send inputs.iccid with a top-up offer.
Top-up rules:
quantitymust be 1, and a top-up is always instant.isInstant: falsegives400 / 10001(NOT_ALLOWED) atitems[i].inputs.isInstant.- An ICCID that is not 18 to 22 digits gives
400 / 10001(INVALID_VALUE) atitems[i].inputs.iccid. - An unknown ICCID, or one that is not yours, gives
404 / 10004. - A package that can no longer top up the eSIM, for example because the eSIM was revoked, gives
400 / 10001. - On the order item,
purchasedProduct.details.orderTypeistopUp(oresimfor a new eSIM), andfulfillment.result.details.modeistopUp.
Instant and deferred eSIMs
inputs.isInstant decides when the eSIM is created.
- Instant (the default): fulfillment creates the eSIM. The item becomes
fulfilledwithmodeinstant,provisioning.statusready, the ICCID and the installation details. While delivery is not yet confirmed, the item stayspending. - Deferred (
isInstant: false): fulfillment delivers an entitlement. The item isfulfilledwithmodedeferred,provisioning.statusnotStarted,canProvisiontrue,esimStatusnew, and no ICCID orinstallationyet. Create the eSIM later withPOST /v1/esims/{id}/provisioning, whereidis the order item id.
Provisioning a deferred eSIM:
- Send an
Idempotency-Key. The optional body is{ "travelStartDate": "2026-12-01" }. - It returns the eSIM as
GET /v1/esims/{iccid}/profiledoes, and updates the item's result.provisioning.statusmoves toprocessingand thenready, and each published change is sent in anorder.fulfillment.updatedwebhook. - Repeating a provisioning that already succeeded, with the same key and body, returns
200with the provisioned eSIM and provisions nothing again. While the first call is still running, the answer is409 / 12002with aRetry-Afterheader. - Only a deferred eSIM can be provisioned. An instant eSIM gives
400 / 10001. An id that is not one of your eSIM purchases, such as a top-up item, gives404 / 10004. - A plan that requires
travelStartDateneeds it here unless the order sent one (400 / 10001). A date different from the recorded one, or a new date after provisioning started, gives409 / 10005. - If provisioning is refused for good, the item becomes
rejectedwithresultnull and a11001failure, the order readsfulfillmentFailed(orpartiallyFulfillednext to delivered items), and the item is refunded in full automatically.
The order item
An eSIM order item carries purchasedProduct, what was bought, and fulfillment.result, what was delivered. There is no value and no deliveredValue.
{
"id": "01a14329-9cc4-73a3-8ca6-22a3efdde687",
"orderId": "01a14329-9cb7-7b0e-9a28-981df5e29f24",
"productType": "esim",
"price": { "amount": 25.00, "currency": "USD" },
"purchasedProduct": {
"name": "Europe 3 GB 7 days",
"countryCode": null,
"logoUrl": "https://example.com/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": "fulfilled",
"result": {
"details": {
"iccid": "8944501234567890123",
"mode": "instant",
"provisioning": { "status": "ready" },
"canProvision": false,
"esimStatus": "ready",
"profileStatus": "new",
"installation": {
"lpaCode": "LPA:1$smdp.example.com$example-activation-code",
"smdpAddress": "smdp.example.com",
"activationCode": "example-activation-code",
"qrCodeUrl": null,
"iosQuickInstall": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$example-activation-code",
"androidQuickInstall": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$example-activation-code"
},
"pin": null,
"puk": null,
"phoneNumber": null,
"data": { "amount": 3072, "unit": "MB", "isUnlimited": false, "label": "3 GB" },
"voice": null,
"sms": null,
"apn": { "apn": "internet", "apnUsername": null, "apnPassword": null },
"addons": [],
"notes": [ "Data only. Calls and SMS are not included." ],
"fulfilledAt": "2026-10-16T05:22:43.59Z"
}
},
"failure": null
},
"actions": {
"amendment": { "availability": "notAvailable", "reason": null },
"cancellation": { "availability": "notAvailable", "reason": null },
"update": { "availability": "notAvailable", "reason": null }
},
"createdAt": "2026-10-16T05:22:43.059969Z",
"effectivePaidAmount": { "amount": 25.00, "currency": "USD" }
}Before fulfillment, the same item has fulfillment.status pending and result null.
purchasedProduct:
inputsechoes the item's inputs.eid,imei2andiccidare masked as***followed by the last four characters.travelStartDateandisInstantare returned as applied. An input the item did not take is null, and the price guard is not echoed.details.orderTypeisesimortopUp.details.destinationis{ id, name, code }.
fulfillment.result.details:
| Key | Meaning |
|---|---|
iccid | The eSIM's ICCID. It addresses the post-purchase routes and top-ups. Null until the eSIM is provisioned. |
mode | instant or deferred for a new eSIM, topUp for a top-up. |
provisioning | { status }: notStarted, processing, ready or failed. |
canProvision | True while a deferred eSIM waits for provisioning. |
esimStatus | new, procuring, pending, failed, ready, cancelled, revoked, expired or unknown. |
profileStatus | The installed profile's state: empty, new, downloaded, installed, activated, inactive, deleted, revoked, expired or unknown. |
installation | lpaCode, smdpAddress, activationCode, qrCodeUrl, iosQuickInstall and androidQuickInstall. Null until the eSIM is provisioned. Generate a QR code from lpaCode when qrCodeUrl is null. |
pin, puk, phoneNumber | Set when they are issued. |
data, voice, sms, apn | The plan, in the shapes and units of the offer. voice and sms are null when the plan has none. |
addons | Top-ups applied to the eSIM, as { packageName, usage }. |
notes | The plan's usage notes. |
fulfilledAt | When the eSIM was delivered. |
A top-up item reads the eSIM it topped up, with mode topUp, and cannot be provisioned.
GET /v1/orders/{id} and the order.fulfillment.updated webhook (reference) carry the same result. See Orders for order and item statuses.
An eSIM cannot be cancelled, amended or updated once delivered. Cancel and its preview answer 422 / 18000, amendments 422 / 18002, and update 422 / 18004. While the eSIM is still pending, cancel answers 409 / 18001. A rejected eSIM is refunded in full automatically and reported by the order-item.refunded webhook.
After the purchase
Routes under /v1/esims/{iccid}/ read one of your eSIMs by ICCID. An ICCID that is not one of your eSIMs gives 404 / 10004.
| Route | Returns |
|---|---|
GET /v1/esims/{iccid}/profile | The eSIM: plan, installation details, status, expiresAt and the base plan's usage. |
GET /v1/esims/{iccid}/usage | Current usage, with top-ups added to the plan. |
GET /v1/esims/{iccid}/usage/details | Usage plus a per-day breakdown in usages. |
GET /v1/esims/{iccid}/usage/history | Recorded usage readings, paged. |
GET /v1/esims/{iccid}/status-events | Status changes over time, paged. |
GET /v1/esims/{iccid}/location-events | Network and location events, paged. |
POST /v1/esims/{iccid}/sms | Sends a text message to the eSIM. Body: { "message": "..." }. |
The three paged event and history routes take page, limit (1 to 100), from and to (ISO 8601 UTC).
Usage conventions:
startandendare ISO 8601 UTC instants. Amounts use one unit each:allowedDataandremainingDatain MB,allowedSmsandremainingSmsin messages,allowedVoiceandremainingVoicein whole minutes.- An amount is null when it is unlimited (the matching
isDataUnlimited,isSmsUnlimitedorisVoiceUnlimitedis then true), not reported or not included. A known allowance that is used up reads0. - In
usage/details,dateis the calendar day the usage was counted for (YYYY-MM-DD), and it is not always a UTC day.start(inclusive) andend(exclusive) are the UTC instants that day runs between. profile.expiresAtis null until the eSIM is activated, then the end of the plan, extended by top-ups.
SMS:
200with{ "iccid": "..." }means the message was sent.422 / 22000means the eSIM's plan cannot send text messages. Do not retry it.502 / 10008means the message could not be sent.
Webhooks
Subscribe to these events to follow an eSIM without polling. See Webhooks for signatures, retries and deduplication by eventId.
esim.profileStatus.updatedis sent when the installed profile's status changes. Its data hasorderId,orderItemId,iccid,start,endandprofileStatus.esim.usage.updatedis sent when usage crosses a threshold. A limited plan advances through 25, 50, 75, 90 and 100 percent used. An unlimited plan advances through 14, 7, 3 and 1 days left. Each threshold is sent at most once per eSIM, and a top-up does not reset it.order.fulfillment.updatedcarries delivery and each provisioning change of a deferred eSIM.
{
"eventId": "677335a8-e904-ff5c-9186-c9c2690461cd",
"eventType": "esim.usage.updated",
"timestamp": 1792128163,
"data": {
"orderId": "01a14329-9cb7-7b0e-9a28-981df5e29f24",
"orderItemId": "01a14329-9cc4-73a3-8ca6-22a3efdde687",
"iccid": "8944501234567890123",
"start": "2026-10-16T05:30:00Z",
"end": "2026-10-23T05:30:00Z",
"esimStatus": "ready",
"profileStatus": "activated",
"packageName": "Europe 3 GB 7 days",
"allowedData": 3072,
"remainingData": 768,
"isDataUnlimited": false,
"allowedSms": null,
"remainingSms": null,
"isSmsUnlimited": false,
"allowedVoice": null,
"remainingVoice": null,
"isVoiceUnlimited": false
}
}timestamp is Unix seconds. Both eSIM events address the eSIM by orderId, orderItemId and iccid.
Testing in Sandbox
Use Sandbox with your Sandbox key. Authentication, pricing, wallet payment, refunds and webhooks behave as in production. The catalog is synthetic: prices and outcomes are test data, and the install details cannot install a working eSIM.
Scenarios
POST /v1/esims/order and the shared POST /v1/orders accept the OpenRoam-Sandbox-Scenario header:
| Value | Result |
|---|---|
Omitted or success | The ordinary successful result. |
fulfillment.rejected | The order is accepted and paid, then fulfillment is rejected. The item is refunded automatically. |
fulfillment.pending | The item stays pending without blocking, and becomes eligible for success after about 15 minutes. |
fulfillment.late_success | Pending, then success after about 2 minutes. |
fulfillment.late_rejected | Pending, then rejection after about 2 minutes. |
curl -X POST https://api.sandbox.openroam.com/v1/esims/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "OpenRoam-Sandbox-Scenario: fulfillment.late_success" \
-H "Content-Type: application/json" \
-d @esim-order.json- The scenario is saved with the order and takes part in idempotency. The same key and body replay the order. The same key with a different scenario returns
409. - Search, quote and reads take no scenario header. Sending it there, or outside Sandbox, returns
400 / 10001(NOT_ALLOWED). An unknown, empty or repeated value returns400 / 10001(INVALID_VALUE). - Timing is approximate and is not a guarantee. A pending item may show
fulfillment.progresswith codeCONFIRMING_OUTCOME. For an instant eSIM or a top-up,resultis null until the outcome arrives. A deferred eSIM still delivers its entitlement at checkout, and the timing applies to its later provisioning. - By default Sandbox fulfillment takes a few seconds, so read the order again before you assume a final state.
Sandbox catalog
The Sandbox catalog has 73 destinations and 587 finite data-only plans: 64 countries, eight regions and a global destination. There are no unlimited, voice or SMS plans. Do not hardcode offer ids: search returns them. These plans cover the input and top-up cases:
| Destination | Data | Validity | Extra inputs | Top-up |
|---|---|---|---|---|
Azerbaijan (AZ, local) | 1024 MB | 7 days | none | yes |
Azerbaijan (AZ, local) | 1024 MB | 3 days | eid | no |
Azerbaijan (AZ, local) | 2048 MB | 7 days | imei2 | no |
Azerbaijan (AZ, local) | 3072 MB | 10 days | travelStartDate | no |
Azerbaijan (AZ, local) | 5120 MB | 30 days | eid, imei2, travelStartDate | yes |
Europe (EU, regional) | 3072 MB | 7 days | none | yes |
Find them with GET /v1/esims/search?countryCode=AZ&category=local, optionally with validityDays. For regional coverage use countryCode=FR&category=regional and pick the destination whose details.destinationCode is EU. For global coverage use countryCode=US&category=global.
Use synthetic inputs such as eid 89049032000000000000000000000001 and imei2 490154203237518. Set travelStartDate to tomorrow's UTC date. To test a deferred eSIM with the 3072 MB / 10 day plan, order with inputs.isInstant: false and send the date at provisioning.
Sandbox behavior to expect:
- An instant purchase gives each eSIM its own ICCID.
qrCodeUrlcan be null, so generate a QR code fromlpaCode. - A top-up adds its validity to the existing eSIM. Top-up search on an eSIM from a plan marked "no" is empty.
- A Sandbox eSIM is never activated and nothing consumes data. Usage shows the plan's allowance plus completed top-ups,
usage.endandprofile.expiresAtstay null, andusage/detailsreturns no daily events. POST /v1/esims/{iccid}/smsanswers200with{ iccid }and sends no real message.
Errors
Paths below are for the items[] bodies. They are prefixed with items[i]. on quote, order and the shared order.
| Status / code | When | Path (reason) |
|---|---|---|
400 / 10001 | A new eSIM is missing an input its offer requires | inputs.<name> (REQUIRED) |
400 / 10001 | inputs.value, or value or maxPrice beside inputs | the field path (INVALID_VALUE) |
400 / 10001 | inputs.maxPrice in another currency than the order | inputs.maxPrice.currency (CURRENCY_MISMATCH) |
400 / 10001 | Top-up with isInstant: false, or a quantity other than 1 | inputs.isInstant (NOT_ALLOWED), quantity (INVALID_VALUE) |
400 / 10001 | Invalid ICCID | inputs.iccid (INVALID_VALUE) |
400 / 10001 | Unknown query parameter, invalid filter, or a malformed or mismatched catalog cursor | the parameter |
400 / 11004 | Unknown, malformed or foreign publicId, an item id, or an offer of another product | items[i] (EXPIRED_OR_INVALID) |
409 / 11003 | The offer cannot be sold now | items[i] (UNAVAILABLE) |
409 / 11002 | The current price is above inputs.maxPrice | inputs.maxPrice (PRICE_CHANGED) |
404 / 10004 | Unknown or foreign ICCID, unknown destination | none |
403 / 10003 | eSIM is not enabled for your account, or the key lacks the manage permission | service (SERVICE_NOT_ENABLED) |
422 / 22000 | SMS to an eSIM whose plan cannot send texts | none |
502 / 10008 | SMS could not be sent | none |
Check which services are enabled with GET /v1/account/services. Idempotency errors are shared across products; see Idempotency. For the common error format and the remaining codes, see Errors.
Next steps
- Quickstart for your first order.
- Authentication and Environments for keys and hosts.
- Orders for order and item status, cancellation and amendments.
- Webhooks for signing and retries.