eSIMs
This page is about travel eSIMs. Selling gift cards instead? See Gift card products.
What you receive, the kinds of plan and the life of an eSIM.
The eSIM endpoints sell travel data eSIMs for a country, a region or the whole world. They all live under /esim/…. Keys, balances and errors work exactly as in the rest of the API: see Authentication, Balances & amounts and Errors.
Only plans delivered instantly are sold through the API.
What you receive
For every eSIM you get the raw install details, and never a NovaCodes page or link. You show them in your own app, page or email, so your customer only sees you.
| Field | What it is |
|---|---|
| iccid | The serial number of the eSIM. It is the eSIM’s id in every later call. |
| install.lpa | The full activation text, in the form LPA:1$address$code. A phone accepts it as a QR code or as pasted text. |
| install.smdp_address | The SM-DP+ address: the address inside the activation text, for phones where the details are typed in by hand. |
| install.activation_code | The activation code: the code inside the activation text, for the same screen. |
| install.qr_svg | The activation text as a QR code, in SVG. Ready to show. |
| install.ios_install_url | Apple’s install link. On an iPhone it opens eSIM set-up directly, without scanning a QR code. |
How to show them: eSIM orders → Showing the QR.
Fixed and daily plans
| type | What the customer gets | How you order it |
|---|---|---|
| fixed | An amount of data (data_mb) to use within a number of days (days). | The plan has one price. Send the plan and a quantity. |
| daily | An amount of data per day (data_mb each day). When a day's data is used, the speed drops to after_daily_limit until the next day. | You choose the number of days, between min_days and max_days, and send it as days. The price depends on it. |
Details: eSIM destinations & plans.
The calls
| Call | What it does | Page |
|---|---|---|
| GET /esim/destinations | Countries, regions and global plans on sale. | Destinations & plans |
| GET /esim/destinations/{code or slug} | One destination with its plans, at your prices. | Destinations & plans |
| GET /esim/plans/{plan_id} | One plan with its coverage and networks. Prices a daily plan for a number of days. | Destinations & plans |
| POST /esim/orders | Buys 1 to 30 eSIMs of one plan. | Orders |
| GET /esim/orders/{number or reference} | One order, install details included. | Orders |
| GET /esim/orders | Your eSIM orders, without install details. | Orders |
| GET /esim/esims/{iccid} | State and data used of one eSIM. | Manage an eSIM |
| GET /esim/esims/{iccid}/topups | The plans that can be added to this eSIM. | Manage an eSIM |
| POST /esim/esims/{iccid}/topups | Adds data to this eSIM. | Manage an eSIM |
| POST /esim/esims/{iccid}/cancel | Cancels a never-installed eSIM for a refund. | Manage an eSIM |
Order status
An order (of new eSIMs, or of a top-up) has one of four statuses. How to handle each one: eSIM orders → Order status.
| status | Meaning |
|---|---|
| completed | Every eSIM is ready. The install details are in the order. |
| processing | Paid, and the eSIMs are still being prepared. Read the order again every few seconds. |
| partial_refunded | Some eSIMs are ready. The purchase of the others was refused, and their price is back in your balance. |
| refunded | The purchase was refused. The full amount is back in your balance. |
The life of an eSIM
Each eSIM has a state, separate from the status of the order that bought it. It normally moves ready → installed → in_use → depleted or expired.
| state | Meaning | What is possible |
|---|---|---|
| ready | Delivered, and not installed on any phone yet. | Install it. Cancel it for a refund. Top it up. |
| installed | On a phone, and no data has been used yet. | Top it up. It can no longer be cancelled. |
| in_use | Data has been used. | Top it up. |
| depleted | All the data has been used. | Top it up to use it again. |
| expired | The plan’s days are over, or the eSIM was not used in time. | Nothing. Sell a new eSIM. |
| cancelled | Cancelled before it was installed, and refunded. | Nothing. install is null. |
| revoked | Withdrawn by the network. It no longer works. | Contact us. install is null. |
A top-up is only possible when the eSIM's top_up is true: not every plan allows it.