Tizondocs
Guides

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.

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.

EntryForNeedsNotes
install_links.iosiPhone or iPadiOS 17.4 or laterWorks on every supported iPhone.
install_links.androidAndroid phoneAndroid 10+ with current Google Play servicesStill 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. active is the one in use. queued is one bought on top, which starts when the active one runs out. An unlimited plan has unlimited: true and 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 a queued plan.

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_links is built each time you retrieve an order, so the format can follow Apple and Google. An order.fulfilled webhook carries lpa but not the links: fetch the order when you get one.
  • The device must be eSIM-capable and unlocked, whichever way it installs.

On this page