Top up an eSIM

Topping up is a two-step flow: first check what's available for the exact ICCID, then submit the topup using one of the returned package_id values. Always follow this order — see Supplier continuity for why.

1. Check available topup packages

GET /api/v1/esims/topup-packages/{iccid}

Permission: Read

Queries the fulfilling supplier live, scoped to this ICCID, so the result always reflects current availability — including the rare case where the country's underlying network operator changed since the eSIM was issued.

curl --request GET \
  --url 'https://api.fx-port.com/api/v1/esims/topup-packages/8900000338153738419?locale=en&force=false' \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY'

Response example

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "elan-7days-1gb-topup",
        "type": "topup",
        "title": "1 GB - 7 days",
        "data": "1 GB",
        "day": 7,
        "is_unlimited": false,
        "price": 8.50,
        "retail_price": 9.52,
        "total_price": 9.52,
        "balance_debit_amount": 8.50,
        "agency_commission": "12 %",
        "currency": "EUR",
        "supplier_currency": "USD"
      }
    ]
  }
}

An empty data.data array means this eSIM currently cannot be topped up — place a new eSIM order for the traveler instead.

2. Create the topup

POST /api/v1/esims/topups

Permission: Read+Write

Use data.data[0].id from step 1 as package_id, and the same ICCID you just queried.

curl --request POST \
  --url https://api.fx-port.com/api/v1/esims/topups \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "package_id": "elan-7days-1gb-topup",
    "iccid": "8900000338153738419",
    "first_name": "Ana",
    "last_name": "Kova",
    "email": "[email protected]",
    "phone": "+34600123456"
  }'

Body fields

Verified directly against the running API — sending a request without email or without phone returns 400.

Response example

{
  "success": true,
  "data": {
    "topup": {
      "code": "20260827-088430",
      "validity": 7,
      "price": 9.52,
      "currency": "EUR",
      "net_price": 8.50,
      "total_price": 9.52,
      "agency_currency": "EUR",
      "supplier_currency": "USD",
      "exchange_rate": 0.92
    },
    "iccid": "8900000338153738419",
    "balance": {
      "previous": 500.00,
      "current": 490.48,
      "currency": "EUR"
    }
  },
  "booking_id": "FX-1787829778186",
  "message": "eSIM topup completed successfully"
}

Does a topup extend or replace the current plan?

Topping up an active eSIM adds the new package's data allowance — it does not replace or shorten what the traveler already has. Depending on the specific package's own validity terms, the new validity window can extend from the topup date rather than simply stacking on the original expiry, so the exact number of remaining days after a topup can vary by package. Always confirm the traveler's actual remaining balance and expiry with eSIM usage after a topup rather than assuming a fixed day-count formula — this mirrors general guidance published by eSIM API providers, which recommend checking usage/status rather than hard-coding validity math.

Example: an eSIM originally issued for 3 days, topped up with a 15-day package, will show additional data and a new expiry reflecting the added validity once you re-check usage — verify the exact resulting remaining and expired_at values for your specific package rather than assuming "3 + 15" arithmetic.

Errors