Integrating eSIM into an existing product is a modest piece of engineering with an unusual failure profile. The API surface is small, the flows are simple, and almost all the difficulty sits outside the API in the period between a customer paying and their phone being connected in another country.
This is a practical guide to what the integration involves: the operations you actually need, how to model orders and profile state, the mistakes that cost real money, and what to build beyond the happy path.
What you are actually building
- Four operations cover most integrations: check compatibility, order a profile, deliver it, report usage.
- The hard part is not the API. It is the twenty minutes after purchase.
- Order creation must be idempotent, because a duplicate order is a real profile you have paid for.
- Webhooks matter more than polling for usage and expiry.
- Test on real iOS and Android devices before you ship. Simulators do not install eSIM profiles.
Why integrate rather than link out
The commercial case is straightforward. Kaleido Intelligence found 89% of travellers would rather buy connectivity from a provider they already have a relationship with, against 60% from an unfamiliar specialist, and GSMA research found 51% of eSIM users first tried the technology while travelling. If your product already serves travellers, issuing the eSIM inside your own flow captures both advantages. Linking out to a partner hands them away.
Typical time from decision to first sale
Typical project durations with an established wholesale partner. API work is longer than a storefront and a fraction of an MVNO build.
Sources: Kaleido Intelligence, 2026; GSMA consumer research.
The trade-off is time. A white-label storefront can be live in two to six weeks with no engineering. An API integration typically runs four to twelve weeks depending on how much of the activation experience you build yourself. Both are a fraction of an MVNO build, and the API route is the one that produces durable economics.
The operations you actually need
Most providers expose more than this. Most integrations use these.
| Operation | What it does | When you call it | Watch for |
|---|---|---|---|
| Catalogue / packages | Lists available plans by country or region | Cache it; do not call per page view | Prices and availability change; refresh on a schedule |
| Device eligibility | Checks whether a device can take an eSIM | Before payment, not after | Not all providers expose this; you may need your own list |
| Create order | Reserves and generates a profile | After successful payment authorisation | Must be idempotent; a retry should not create a second profile |
| Retrieve profile | Returns the activation code and QR | Immediately after order, and on demand later | Customers lose emails; make this re-retrievable in-product |
| Usage | Consumption and remaining allowance | On demand, plus webhook thresholds | Ask whether it is real-time or batched |
| Top-up | Adds data to an installed profile | At a usage threshold or on request | Must not require reinstallation |
| Webhooks | Pushes installation, threshold and expiry events | Configure once, verify signatures | Handle retries and out-of-order delivery |
Endpoint names differ by provider. These are the capabilities to confirm exist before you scope the work.
Device eligibility is the row most often skipped and most often regretted. Not every provider exposes a compatibility endpoint, and where they do not you will need to maintain your own device list. Either way the check belongs before the payment sheet, because selling a profile to a handset that cannot install one produces a guaranteed refund and a support conversation with someone who is probably already abroad.
Modelling profile state
A profile moves through a defined lifecycle, and your product should reflect where the customer actually is rather than treating everything after purchase as one state.
| State | What it means | What your UI should show |
|---|---|---|
| Ordered | Profile generated, not yet downloaded | The QR code and install instructions |
| Downloaded | Profile is on the device, not yet in use | Reminder to enable it and set it as the data line |
| Installed and enabled | Active on the device | Remaining allowance and validity end date |
| In use | Consuming data | Live usage, plus a top-up route |
| Depleted | Allowance exhausted | Top-up prompt, ideally before this point |
| Expired | Validity window has ended | Clear explanation and a repurchase path |
Exact state names vary by provider. What matters is that every one of these is visible to your support team.
The gap between downloaded and enabled causes more support volume than anything else. A customer can install a profile correctly, leave their home line as the data line, and conclude the product does not work. If you can detect the installed-but-not-enabled state, prompting at that point removes a whole class of tickets.
Mistakes and what to build instead
Integration mistakes that cost money
- Non-idempotent order creation, so retries buy duplicate profiles
- Ordering before payment settles
- Only delivering the QR by email
- Polling usage on a tight loop instead of using webhooks
- No compatibility check before checkout
- Storing activation codes without treating them as secrets
What to build beyond the happy path
- Re-retrieve the QR from inside your own product
- A support view showing live profile state
- Reissue without escalating to your provider
- Threshold alerts before the allowance runs out
- Clear expiry messaging with a repurchase path
- Reconciliation between your orders and provider billing
Email-only delivery is the most common design shortcut and it fails predictably. A traveller looking for their QR code is usually in an airport, on unreliable wifi, searching an inbox for a message they received weeks earlier. Making the activation code retrievable from inside your own app or account area removes that failure entirely, and it is a small amount of work.
A sequence that works
Get sandbox access before you scope
Issue a test profile end to end and install it on a real handset. You will learn more in an afternoon about what the integration actually requires than from any amount of documentation review, and it surfaces platform limitations while you can still change provider.
Model the order as a payment-linked transaction
A profile is a real purchase against your wholesale account the moment it is created. Order after payment authorisation, make creation idempotent with your own reference key, and reconcile daily against provider records.
Put compatibility before the payment sheet
Selling to a device that cannot install a profile guarantees a refund and a support ticket. Check eligibility earlier than feels necessary, and handle the negative case with an explanation rather than a dead end.
Own the delivery, not just the email
Customers lose emails, especially while travelling. The activation code needs to be retrievable from inside your product, with installation instructions for the platform the customer is actually using.
Wire webhooks before launch, not after
Installation, usage thresholds and expiry are the events that let you prompt at the right moment. Verify signatures, handle retries, and assume events can arrive out of order or more than once.
Build the support view first, not last
Whoever answers your customers needs to see profile state without logging into your provider. Building it early also forces you to model the states properly in your own system.
Step six is worth doing out of order deliberately. Building the internal support view early forces you to model profile state properly in your own database rather than treating the provider as the source of truth, and it means the people answering customers on launch day can actually see what is happening.
Frequently asked questions
Get sandbox access before you scope the work
eSIM Island provides API access with real-time usage, webhooks, profile diagnostics and self-service reissue, plus test credentials so you can build against it before committing. Tell us about your product and target markets and we will set you up.
Book a Free Demo
Leave a Reply