Skip to Content
OpenRoam Docs

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

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:

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:

  • id is the destination id. publicId on an offer is the id you quote and order with. Treat both as opaque. A destination id is never orderable; sent as a publicId it gives 400 / 11004.
  • countryCode is an ISO 3166-1 alpha-2 code for a local destination and null for a regional or global one. details.destinationCode is the destination's own code, such as FR, EU or NAM.
  • price is indicative. The quote is authoritative.
  • details.data.amount is in MB. It is null when isUnlimited is true or the amount is not known.
  • details.properties.withTopUp tells you whether the plan can be topped up.
  • After a purchase, GET /v1/esims/destinations/{id} with the order item's purchasedProduct.details.destination.id returns the coverage of the destination the eSIM was bought for.

Required inputs

Each offer lists the inputs it takes in requiredInputs:

nametypeRequiredListed on
eidtextyesOffers that require the device EID.
imei2textyesOffers that require the device's second IMEI.
travelStartDatedateyesOffers that require the first day of travel (YYYY-MM-DD). A deferred purchase may send it at provisioning instead.
isInstantbooleannoEvery purchase offer. true (the default) creates the eSIM when the order is fulfilled. false delivers an entitlement.
iccidtextyesTop-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.json

The 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 quantity above 1, and each eSIM becomes its own order item. A top-up takes quantity 1.
  • referenceId is your own reference. Quote validates it and ignores it.
  • inputs.value does not exist for eSIM. Sending it, or sending value or maxPrice beside inputs, fails with 400 / 10001 and reason INVALID_VALUE.
  • inputs.maxPrice is { amount, currency }, the highest unit price you accept, in the order currency. A current price above it fails with 409 / 11002 (PRICE_CHANGED) at items[i].inputs.maxPrice, and nothing is charged. A different currency gives 400 / 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.

  1. 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 only iccid in requiredInputs. The result is empty when no plan can top the eSIM up. With iccid, every filter other than currency is rejected (NOT_ALLOWED).
  2. Quote and order that offer with inputs.iccid. Read the ICCID from the purchase's fulfillment.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:

  • quantity must be 1, and a top-up is always instant. isInstant: false gives 400 / 10001 (NOT_ALLOWED) at items[i].inputs.isInstant.
  • An ICCID that is not 18 to 22 digits gives 400 / 10001 (INVALID_VALUE) at items[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.orderType is topUp (or esim for a new eSIM), and fulfillment.result.details.mode is topUp.

Instant and deferred eSIMs

inputs.isInstant decides when the eSIM is created.

  • Instant (the default): fulfillment creates the eSIM. The item becomes fulfilled with mode instant, provisioning.status ready, the ICCID and the installation details. While delivery is not yet confirmed, the item stays pending.
  • Deferred (isInstant: false): fulfillment delivers an entitlement. The item is fulfilled with mode deferred, provisioning.status notStarted, canProvision true, esimStatus new, and no ICCID or installation yet. Create the eSIM later with POST /v1/esims/{id}/provisioning, where id is 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}/profile does, and updates the item's result. provisioning.status moves to processing and then ready, and each published change is sent in an order.fulfillment.updated webhook.
  • Repeating a provisioning that already succeeded, with the same key and body, returns 200 with the provisioned eSIM and provisions nothing again. While the first call is still running, the answer is 409 / 12002 with a Retry-After header.
  • 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, gives 404 / 10004.
  • A plan that requires travelStartDate needs it here unless the order sent one (400 / 10001). A date different from the recorded one, or a new date after provisioning started, gives 409 / 10005.
  • If provisioning is refused for good, the item becomes rejected with result null and a 11001 failure, the order reads fulfillmentFailed (or partiallyFulfilled next 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:

  • inputs echoes the item's inputs. eid, imei2 and iccid are masked as *** followed by the last four characters. travelStartDate and isInstant are returned as applied. An input the item did not take is null, and the price guard is not echoed.
  • details.orderType is esim or topUp. details.destination is { id, name, code }.

fulfillment.result.details:

KeyMeaning
iccidThe eSIM's ICCID. It addresses the post-purchase routes and top-ups. Null until the eSIM is provisioned.
modeinstant or deferred for a new eSIM, topUp for a top-up.
provisioning{ status }: notStarted, processing, ready or failed.
canProvisionTrue while a deferred eSIM waits for provisioning.
esimStatusnew, procuring, pending, failed, ready, cancelled, revoked, expired or unknown.
profileStatusThe installed profile's state: empty, new, downloaded, installed, activated, inactive, deleted, revoked, expired or unknown.
installationlpaCode, smdpAddress, activationCode, qrCodeUrl, iosQuickInstall and androidQuickInstall. Null until the eSIM is provisioned. Generate a QR code from lpaCode when qrCodeUrl is null.
pin, puk, phoneNumberSet when they are issued.
data, voice, sms, apnThe plan, in the shapes and units of the offer. voice and sms are null when the plan has none.
addonsTop-ups applied to the eSIM, as { packageName, usage }.
notesThe plan's usage notes.
fulfilledAtWhen 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.

RouteReturns
GET /v1/esims/{iccid}/profileThe eSIM: plan, installation details, status, expiresAt and the base plan's usage.
GET /v1/esims/{iccid}/usageCurrent usage, with top-ups added to the plan.
GET /v1/esims/{iccid}/usage/detailsUsage plus a per-day breakdown in usages.
GET /v1/esims/{iccid}/usage/historyRecorded usage readings, paged.
GET /v1/esims/{iccid}/status-eventsStatus changes over time, paged.
GET /v1/esims/{iccid}/location-eventsNetwork and location events, paged.
POST /v1/esims/{iccid}/smsSends 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:

  • start and end are ISO 8601 UTC instants. Amounts use one unit each: allowedData and remainingData in MB, allowedSms and remainingSms in messages, allowedVoice and remainingVoice in whole minutes.
  • An amount is null when it is unlimited (the matching isDataUnlimited, isSmsUnlimited or isVoiceUnlimited is then true), not reported or not included. A known allowance that is used up reads 0.
  • In usage/details, date is the calendar day the usage was counted for (YYYY-MM-DD), and it is not always a UTC day. start (inclusive) and end (exclusive) are the UTC instants that day runs between.
  • profile.expiresAt is null until the eSIM is activated, then the end of the plan, extended by top-ups.

SMS:

  • 200 with { "iccid": "..." } means the message was sent.
  • 422 / 22000 means the eSIM's plan cannot send text messages. Do not retry it.
  • 502 / 10008 means 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.updated is sent when the installed profile's status changes. Its data has orderId, orderItemId, iccid, start, end and profileStatus.
  • esim.usage.updated is 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.updated carries 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:

ValueResult
Omitted or successThe ordinary successful result.
fulfillment.rejectedThe order is accepted and paid, then fulfillment is rejected. The item is refunded automatically.
fulfillment.pendingThe item stays pending without blocking, and becomes eligible for success after about 15 minutes.
fulfillment.late_successPending, then success after about 2 minutes.
fulfillment.late_rejectedPending, 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 returns 400 / 10001 (INVALID_VALUE).
  • Timing is approximate and is not a guarantee. A pending item may show fulfillment.progress with code CONFIRMING_OUTCOME. For an instant eSIM or a top-up, result is 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:

DestinationDataValidityExtra inputsTop-up
Azerbaijan (AZ, local)1024 MB7 daysnoneyes
Azerbaijan (AZ, local)1024 MB3 dayseidno
Azerbaijan (AZ, local)2048 MB7 daysimei2no
Azerbaijan (AZ, local)3072 MB10 daystravelStartDateno
Azerbaijan (AZ, local)5120 MB30 dayseid, imei2, travelStartDateyes
Europe (EU, regional)3072 MB7 daysnoneyes

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. qrCodeUrl can be null, so generate a QR code from lpaCode.
  • 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.end and profile.expiresAt stay null, and usage/details returns no daily events.
  • POST /v1/esims/{iccid}/sms answers 200 with { 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 / codeWhenPath (reason)
400 / 10001A new eSIM is missing an input its offer requiresinputs.<name> (REQUIRED)
400 / 10001inputs.value, or value or maxPrice beside inputsthe field path (INVALID_VALUE)
400 / 10001inputs.maxPrice in another currency than the orderinputs.maxPrice.currency (CURRENCY_MISMATCH)
400 / 10001Top-up with isInstant: false, or a quantity other than 1inputs.isInstant (NOT_ALLOWED), quantity (INVALID_VALUE)
400 / 10001Invalid ICCIDinputs.iccid (INVALID_VALUE)
400 / 10001Unknown query parameter, invalid filter, or a malformed or mismatched catalog cursorthe parameter
400 / 11004Unknown, malformed or foreign publicId, an item id, or an offer of another productitems[i] (EXPIRED_OR_INVALID)
409 / 11003The offer cannot be sold nowitems[i] (UNAVAILABLE)
409 / 11002The current price is above inputs.maxPriceinputs.maxPrice (PRICE_CHANGED)
404 / 10004Unknown or foreign ICCID, unknown destinationnone
403 / 10003eSIM is not enabled for your account, or the key lacks the manage permissionservice (SERVICE_NOT_ENABLED)
422 / 22000SMS to an eSIM whose plan cannot send textsnone
502 / 10008SMS could not be sentnone

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

On this page