Top up an eSIM

POST/v1/esims/{iccid}/topupesims:write

Loads another package onto an existing eSIM. No new eSIM is produced — the customer keeps the profile already on their phone and does not reinstall anything.

This is the endpoint for a traveller who has run out of data, and the reason to prefer it over selling a second eSIM.

Headers

Header	Required	Notes
`Idempotency-Key`	Yes	Top-ups spend balance. Omitting it returns `422`. See Idempotency

Path parameters

Name	Notes
`iccid`	The ICCID of the eSIM to top up

Request

Field	Type	Required	Notes
`package_id`	string	Yes	An id from List top-ups — not from the general catalog

curl -X POST https://partner-api.esimfo.com/v1/esims/89852350326100409575/topup \
  -H 'Authorization: Bearer esf_live_at_...' \
  -H 'Idempotency-Key: 3c7a1f95-2e64-4b8d-9a01-7f5c2d8e4b16' \
  -H 'Content-Type: application/json' \
  -d '{ "package_id": "pkg_tr_5gb_30d" }'

Response `201`

A top-up is an order. It returns the same shape as Create an order, so it appears in List orders and in your invoices like any other purchase.

{
  "id": "ord_7e12a4b9",
  "order_number": "ESF-2026-0004833",
  "status": "COMPLETED",
  "payment_mode": "BALANCE",
  "subtotal": "6.10",
  "commission_amount": "0.00",
  "total": "6.10",
  "currency": "EUR",
  "client_reference": null,
  "created_at": "2026-08-22T11:02:19.774Z",
  "items": [
    {
      "package_id": "pkg_tr_5gb_30d",
      "quantity": 1,
      "unit_price": "6.10",
      "line_total": "6.10"
    }
  ],
  "esims": [
    {
      "id": "esm_9a3f1c",
      "iccid": "89852350326100409575",
      "lpa_code": "LPA:1$rsp.truphone.com$QR-G-5C-1LK-1V0FS",
      "qr_code_url": "https://cdn.esimfo.com/qr/esm_9a3f1c.png",
      "smdp_address": "rsp.truphone.com",
      "matching_id": "QR-G-5C-1LK-1V0FS",
      "status": "ACTIVE",
      "data_total_mb": 8192,
      "data_used_mb": 3072,
      "data_remaining_mb": 5120,
      "expires_at": "2026-09-21T00:00:00.000Z",
      "failure_reason": null
    }
  ]
}

Note the ICCID is unchanged and data_total_mb has grown by the new package.

Notes

Pick the package from the eSIM’s own list. Call List top-ups first: what a line can take depends on its operator and state, and the general catalog cannot tell you that. Passing an arbitrary catalog id is the most common cause of a rejected top-up.

A depleted eSIM can be topped up. DEPLETED means the data ran out, not that the profile is dead. EXPIRED is different: the validity window closed and a new eSIM is required.

Failures refund automatically. If the package cannot be loaded, the amount is returned to your balance without you asking.

Errors

Status	Code	Cause
422	`validation_failed`	Missing `Idempotency-Key`, or no `package_id`
404	`not_found`	No such ICCID, or it belongs to another account
422	`insufficient_balance`	Balance does not cover the package
422	`package_not_available`	Package withdrawn, or wrong region for this eSIM
409	`idempotency_key_reused`	Key already used for a different top-up
403	`insufficient_scope`	Key lacks `esims:write`