Installing an eSIM
An install button for iPhone and Android, a QR code for everything else, and the data left once it is in use.
A fulfilled eSIM order carries everything your customer needs to install it. Retrieve the
order and read its deliverable:
curl https://api.tizon.mobile/v1/orders/{order_id} \
-H "Authorization: Bearer $TIZON_KEY""deliverable": {
"type": "esim_profile",
"iccid": "8910300000012345678",
"lpa": "LPA:1$smdp.example.com$MBGNW-2IMOY-XAKHK-CPNCJ",
"activation_code": "MBGNW-2IMOY-XAKHK-CPNCJ",
"smdp_address": "smdp.example.com",
"install_links": {
"ios": {
"url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$MBGNW-2IMOY-XAKHK-CPNCJ",
"device": "iPhone or iPad",
"requires": "iOS 17.4 or later"
},
"android": {
"url": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$MBGNW-2IMOY-XAKHK-CPNCJ",
"device": "Android phone",
"requires": "Android 10 or later with current Google Play services; still rolling out"
}
}
}There are three ways to install it. Offer the best one for the device your customer is on, and keep the others as a fallback.
Install button: install_links
Each entry opens that phone's own eSIM install screen with the profile already filled in. One tap, then the customer confirms in Settings. No camera, no typing.
| Entry | For | Needs | Notes |
|---|---|---|---|
install_links.ios | iPhone or iPad | iOS 17.4 or later | Works on every supported iPhone. |
install_links.android | Android phone | Android 10+ with current Google Play services | Still rolling out: some phones will not respond to it yet. |
Every entry says the same in its own device and requires fields, so you can show them
as a label or a support hint without hard-coding anything.
Pick the entry by the device the eSIM is going on:
const { lpa, install_links } = order.deliverable;
const ua = navigator.userAgent;
const link = /iPhone|iPad/.test(ua)
? install_links.ios
: /Android/.test(ua)
? install_links.android
: null; // a desktop has no install screen: show the QR code below
if (link) {
button.textContent = `Install on your ${link.device}`;
button.href = link.url;
}Open the link on the phone itself, and outside any in-app browser. In a mobile app,
hand it to the system (Linking.openURL in React Native, UIApplication.open on iOS,
an ACTION_VIEW intent on Android) rather than a web view, or nothing happens.
QR code: lpa
lpa is the standard activation string. Render it as a QR code and any eSIM phone can
scan it from its own eSIM settings (usually Add eSIM under mobile or cellular
settings). This is the right choice on a desktop, where the customer installs on a phone
they are holding, and the fallback when an install link does not respond.
Manual entry
For a phone that cannot scan, the customer types smdp_address and activation_code into
the same screen. They are the two halves of lpa. smdp_address is absent where the
provider does not report one; lpa always carries both.
Data left on it
Once the eSIM is in use, read its usage to show your customer what is left, or to offer more data before it runs out:
curl https://api.tizon.mobile/v1/esims/{iccid}/usage \
-H "Authorization: Bearer $TIZON_KEY"{
"object": "esim_usage",
"iccid": "8910300000012345678",
"installed_at": "2026-10-02T11:52:40.000Z",
"plans": [
{
"offer_id": "off_jp_5gb_30d",
"status": "active",
"starts_at": "2026-10-02T11:52:40.000Z",
"ends_at": "2026-11-01T11:52:40.000Z",
"data": { "unit": "GB", "unlimited": false, "total": 5, "remaining": 3.75, "used": 1.25 }
}
]
}- Each plan on the eSIM is listed.
activeis the one in use.queuedis one bought on top, which starts when the active one runs out. An unlimited plan hasunlimited: trueand null figures. - It is measured when you ask, and nothing is pushed. Call it when your customer opens their eSIM, not on a timer for every eSIM you have sold.
- Only eSIMs your own orders issued. Any other ICCID is
404 esim_not_found. - To add data, quote another plan with the same
iccid. It joins the eSIM as aqueuedplan.
Things to know
- A profile installs once. After a successful install, the link, the QR code and the manual details all stop working. Do not let a customer delete the eSIM thinking they can add it again.
- Read the order, not the webhook.
install_linksis built each time you retrieve an order, so the format can follow Apple and Google. Anorder.fulfilledwebhook carrieslpabut not the links: fetch the order when you get one. - The device must be eSIM-capable and unlocked, whichever way it installs.