eSIM & Bundle Status

After ordering an eSIM, you’ll want to monitor its bundles — whether they’re active, how much data remains, and when they expire. This guide covers how to query bundle status and what each state means.

Listing bundles on an eSIM

curl https://api.esim-go.com/v2.5/esims/{iccid}/bundles \
  -H 'X-API-Key: $API_KEY'

By default this returns the 15 most recent bundle assignments. Use limit (max 200) to fetch more, and includeUsed=true to include expired and depleted bundles in the response.

Example response

{
  "bundles": [
    {
      "name": "esim_1GB_7D_GB_V2",
      "description": "eSIM, 1GB, 7 Days, United Kingdom, V2",
      "assignments": [
        {
          "id": "215009266",
          "assignmentReference": "3a6e2e40-c674-45e9-b289-b35027bf72a9-0",
          "callTypeGroup": "data",
          "initialQuantity": 1000000000,
          "remainingQuantity": 750000000,
          "assignmentDateTime": "2024-12-11T10:47:00Z",
          "bundleState": "active",
          "unlimited": false
        }
      ]
    }
  ]
}

Note

initialQuantity and remainingQuantity are in bytes, using base 10 (1 GB = 1,000,000,000 bytes, not 1,073,741,824). To display data in GB: remainingQuantity / 1,000,000,000.

Bundle states

State	Meaning
processing	Assignment is being processed. Usually instant but can take up to 10 minutes. The eSIM can be installed and will register on a network while in this state.
queued	Successfully assigned but not yet used. Waiting for the eSIM to connect and start consuming data.
active	In use. Data remaining and within the bundle duration.
depleted	All data used. Still within the bundle duration but no data remaining.
expired	Bundle duration has passed.
revoked	Manually revoked and removed from the eSIM.
lapsed	Expired without ever being used.

Checking a specific bundle

To query a single bundle by name rather than listing all:

curl https://api.esim-go.com/v2.5/esims/{iccid}/bundles/{name} \
  -H 'X-API-Key: $API_KEY'

Replace {name} with the bundle name, for example esim_1GB_7D_GB_V2. Bundle names are case sensitive.

Best practice: query on demand

Avoid polling bundle status on a schedule for every eSIM in your system. Doing so at scale will quickly hit rate limits and return 429 errors.

Instead, query bundle status on demand — when your end user opens a screen that displays their remaining data or bundle details. This keeps API usage proportional to actual user activity rather than your total eSIM count.