Skip to content
eSIMfoeSIMfo Partner API

List top-ups for an eSIM

GET/v1/esims/{iccid}/topupsesims:read

Returns the packages that can be loaded onto this eSIM.

Top-ups are not sold from the general catalog. What a line can take depends on its operator and its current state, so this list is read from the provider at request time rather than derived from our catalog. Pass an id from here to Top up an eSIM.

Path parameters

Section titled “Path parameters”
Name Notes
iccid The ICCID of the eSIM
Terminal window
curl https://partner-api.esimfo.com/v1/esims/89852350326100409575/topups \
  -H 'Authorization: Bearer esf_live_at_...'

Response 200

Section titled “Response 200”
Field Type Notes
data[].id string Pass this as package_id when topping up
data[].name string Display name
data[].data_amount_mb integer | null null on unlimited top-ups
data[].validity_days integer Days added from activation
data[].currency string ISO 4217
data[].price string What you pay
data[].selling_price string | null What you charge; null when selling prices are hidden 
{
  "data": [
    {
      "id": "pkg_tr_1gb_topup_3d",
      "name": "1 GB — 3 days",
      "data_amount_mb": 1024,
      "validity_days": 3,
      "currency": "EUR",
      "price": "2.80",
      "selling_price": "4.20"
    },
    {
      "id": "pkg_tr_3gb_topup_7d",
      "name": "3 GB — 7 days",
      "data_amount_mb": 3072,
      "validity_days": 7,
      "currency": "EUR",
      "price": "4.60",
      "selling_price": "6.90"
    }
  ]
}

Notes

Section titled “Notes”

No pagination. A single eSIM has a handful of options, not thousands.

An empty list is a valid answer. It means this line cannot take a top-up right now — the eSIM may still be provisioning, or its operator may have closed the top-up window. Show the customer that rather than an error.

Prices are yours. The provider decides which packages are offered; we decide what they cost you, through the same pricing rules as the catalog.

Do not cache aggressively. Availability tracks the eSIM’s state, which changes as data is used and validity elapses.

Errors

Section titled “Errors”
Status Code Cause
404 not_found No such ICCID, or it belongs to another account
403 insufficient_scope Key lacks esims:read