Integration guide

Track activation and usage

Two endpoints cover the whole life of an eSIM: the eSIM itself for status and installation, and its usage for data counters.

Status values

PROVISIONING — the profile is being prepared. Rare in a response, since ordering waits for allocation.
ALLOCATED — issued and ready to install. This is what you deliver.
INSTALLED — downloaded onto a device but not yet used.
IN_USE — attached to a network. Validity is now running.
EXPIRED — validity ended or the bundle was fully consumed.
DELETED — the profile was removed from the device or withdrawn.

When validity starts

Validity starts on first network attachment in the destination, not at purchase and not at installation. A traveller can buy weeks ahead and install at home safely. Because of that, `created_at` is not an expiry base — show the remaining days only once the eSIM reaches `IN_USE`.

Reading usage

bash

curl -s https://app.journeystack.co/api/public/v1/esims/$ESIM_ID/usage -H "Authorization: Bearer $JS_KEY"

json

{
  "data": {
    "esim_id": "9ac2d51b-8f2e-4d6e-b0a1-6c5f0d9a3b77",
    "status": "IN_USE",
    "unlimited": true,
    "total_bytes": null,
    "used_bytes": 734003200,
    "remaining_bytes": null,
    "validity_days": 7,
    "created_at": "2026-01-14T09:31:02.114Z"
  }
}

Counters are in bytes. On unlimited plans total_bytes and remaining_bytes are null — there is no cap to count down.
Figures come from the mobile network and are typically no more than 15 minutes behind live usage.
Usage is not billing. Nothing you read here changes what you were charged at purchase.

Polling versus webhooks

Prefer webhooks: `esim.activated`, `esim.usage_alert` and `esim.expired` arrive without you asking. If you also poll, poll only eSIMs that are `ALLOCATED`, `INSTALLED` or `IN_USE`, at most every 15 minutes. Polling faster returns the same numbers and eats your rate limit.

Sandbox eSIMs never move on their own

A sandbox profile stays ALLOCATED with zero usage, because no real network is involved. Test your status handling by writing the states directly into your own fixtures.

Recharging an eSIM

Topping up an existing eSIM is not part of v1. Today the supported path is to sell a new plan when one runs out — either a fresh eSIM, or a longer purchase up front for per-day plans. When recharge ships it will appear in the changelog as an additive endpoint.