Tizondocs
ReferenceOrders

Retrieve an eSIM's data usage

GET
/v1/esims/{iccid}/usage

How much data is left on each active and queued plan on an eSIM, measured when you ask. Nothing is pushed when usage changes, so call this when you need the figure, such as when a customer opens their eSIM, rather than on a timer.

The eSIM must have been issued by one of this account's own orders. Any other ICCID, including one this account has only topped up, is 404 esim_not_found. If usage cannot be read right now the answer is 502 fulfillment_unavailable: retry shortly.

In sandbox the figures are simulated from what was bought: the oldest plan still within its validity is active with a quarter of its data used, and any bought after it are queued.

Authorization

ApiKey
AuthorizationBearer <token>

An account API key, sent as Authorization: Bearer tz_live_…. The prefix selects the mode: tz_test_ for sandbox, tz_live_ for real money.

In: header

Path Parameters

iccid*string

The iccid from the order's eSIM profile.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/esims/8931440400000000123/usage"
{  "object": "esim_usage",  "iccid": "8931440400000000123",  "installed_at": "2019-08-24T14:15:22Z",  "plans": [    {      "offer_id": "string",      "status": "active",      "starts_at": "2019-08-24T14:15:22Z",      "ends_at": "2019-08-24T14:15:22Z",      "data": {        "unit": "GB",        "unlimited": true,        "total": 5,        "remaining": 3.75,        "used": 1.25      }    }  ]}