eSIM API Integration Guide: Provision eSIMs Programmatically

Integrating an eSIM API is one of the highest-leverage features a travel or telecom product can ship: a few endpoints turn your checkout into a connectivity store. This guide covers the full integration — provisioning, delivery, webhooks, and the edge cases worth handling — from a developer’s perspective.

The core flow

Every eSIM reseller integration reduces to three steps:

1. Customer pays          →  your checkout
2. Provision the eSIM     →  POST /v1/esims
3. Deliver the QR code    →  confirmation page + email

Provisioning

When payment succeeds, your backend makes one call:

curl -X POST https://api.esim.tech/v1/esims \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product": "local-nl-unlimited",
    "reference": "order_8412"
  }'

The response returns everything you need, immediately:

{
  "id": "esim_L4nX...",
  "iccid": "8931089...",
  "lpa": "LPA:1$smdp.esim.tech$K9MX-....",
  "phone_number": "+31612345678",
  "status": "ready",
  "created_at": "2026-07-02T09:41:12Z"
}

Two things matter here. First, the LPA code is in the response — no polling, no email, no async job. At ~120ms end-to-end you can call it synchronously inside checkout. Second, for local eSIM products, the phone number arrives in the same response, so you can show the customer their new local number before they’ve even scanned the QR code.

Delivery

Render the LPA string as a QR code (any QR library; the string is the payload) and:

• Show it on the confirmation page
• Email it as a fallback (customers often install later, on Wi-Fi)
• On mobile, also offer the universal-link install flow so same-device users don’t need a second screen to scan from

Lifecycle webhooks

Register a webhook endpoint and you’ll receive events like:

{ "type": "esim.activated",   "esim": "esim_L4nX", "at": "..." }
{ "type": "usage.threshold",  "esim": "esim_L4nX", "used_mb": 4096, "threshold": 0.8 }
{ "type": "balance.low",      "esim": "esim_L4nX", "remaining_mb": 512 }

The balance.low event is your revenue engine: trigger a one-click top-up email and you monetise the moment of highest intent. Resellers automating this typically see 20–30% extra revenue per customer.

Design decisions worth getting right

Idempotency. Pass your order ID as reference and retry safely on network failures — you never want to provision (and pay for) two eSIMs for one order.

Provision at payment, not before. eSIMs are billed when provisioned. Don’t pre-generate them for abandoned carts.

Store the ICCID. It’s the stable identifier you’ll use for support, top-ups, and usage queries.

Handle the “can my phone do this?” question early. Check eSIM device compatibility in your UI before checkout, not in a refund email after.

Product types you can provision

One integration gives you the full catalogue:

• Pay-as-you-go data — per-MB billing, top-ups via API, 190+ countries
• Local eSIMs — real local phone number + voice + SMS + (unlimited) data in 25+ countries
• EU data bundles — up to 500 GB for routers, campers, and fleets across the EU
• 5G backup — failover connectivity for fixed locations

Same API shape for all of them — only the product identifier changes, so expanding your line-up later is a config change, not a project. If you’re evaluating the business side first, start with how to become an eSIM reseller.

Going live

1. Create your account at resellers.esim.tech
2. Integrate provisioning + QR rendering against the sandbox
3. Wire the webhook endpoint (activation + low balance at minimum)
4. Test the full install flow on a real iPhone and a real Android device
5. Switch to live keys and ship

Authentication is a standard Bearer token, the API is plain REST/JSON, and there are no minimum volumes — your first provisioned eSIM can be a production customer.

Frequently asked questions