Top up an eSIM

Topping up is a two-step flow: first ask which packages can top up this exact eSIM, then create the topup with 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

Lists the packages that can be added to one eSIM, with prices in your agency currency. The answer is scoped to the ICCID, so it reflects what the supplier offers for this eSIM today, including the rare case where the network operator of the country changed since the eSIM was issued.

The ICCID must belong to an eSIM that your agency ordered in the same environment: 18 to 22 digits, which may be written in groups of spaces or hyphens (8944 4654 0000 0123 456; the digits are read). An ICCID that is unknown, or that belongs to another agency, is answered 404 iccid_not_found before anything is asked from the supplier. A sandbox key only sees sandbox eSIMs.

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

const iccid = "8900000540463077957";
const response = await fetch(`https://api.fx-port.com/api/v1/esims/topup-packages/${iccid}?locale=en`, {
  headers: { Authorization: "Bearer fxp_test_YOUR_KEY" },
});
const body = await response.json();
const packages = body.data.data; // the list is one level deeper than the other catalogs

import requests

iccid = "8900000540463077957"
response = requests.get(
    f"https://api.fx-port.com/api/v1/esims/topup-packages/{iccid}",
    params={"locale": "en"},
    headers={"Authorization": "Bearer fxp_test_YOUR_KEY"},
    timeout=30,
)
packages = response.json()["data"]["data"]

Caching. The list is kept for 5 minutes per eSIM and language. A cached answer carries cached: true and cache_age_seconds; a fresh one has neither. Use force=true only when you need the very latest list.

Response example

A sandbox answer (the prices block shortened):

{
  "environment": "sandbox",
  "success": true,
  "data": {
    "data": [
      {
        "id": "france-in-7days-1gb-topup",
        "package_id": "france-in-7days-1gb-topup",
        "type": "topup",
        "price": 468.84,
        "amount": 1024,
        "day": 7,
        "is_unlimited": false,
        "title": "1 GB - 7 days",
        "data": "1 GB",
        "short_info": null,
        "voice": null,
        "text": null,
        "prices": { "recommended_retail_price": { "EUR": 3.56, "GBP": 3, "USD": 4 } },
        "base_price": 402.5,
        "commission": 50.24,
        "total_price": 468.84,
        "retail_price": 468.84,
        "balance_debit_amount": 418.6,
        "b2b_price": 418.6,
        "agency_commission": "12 %",
        "commission_rate": 12,
        "currency": "DZD",
        "supplier_currency": "USD"
      }
    ]
  }
}

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

Package fields

How the amounts relate is explained in eSIM pricing.

2. Create the topup

POST /api/v1/esims/topups

Permission: Read+Write

Send one package_id from step 1 and the ICCID you asked about. Prices are computed on the server; a price in the body is ignored.

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": "france-in-7days-1gb-topup",
    "iccid": "8900000540463077957",
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "+15555550123"
  }'

const response = await fetch("https://api.fx-port.com/api/v1/esims/topups", {
  method: "POST",
  headers: { Authorization: "Bearer fxp_test_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    package_id: "france-in-7days-1gb-topup",
    iccid: "8900000540463077957",
    email: "[email protected]",
    phone: "+15555550123",
  }),
});
const body = await response.json();
if (!response.ok) throw new Error(body.errors?.[0]?.code ?? `HTTP ${response.status}`);
console.log(body.booking_id, body.data.balance);

import requests

response = requests.post(
    "https://api.fx-port.com/api/v1/esims/topups",
    headers={"Authorization": "Bearer fxp_test_YOUR_KEY"},
    json={
        "package_id": "france-in-7days-1gb-topup",
        "iccid": "8900000540463077957",
        "email": "[email protected]",
        "phone": "+15555550123",
    },
    timeout=170,
)
body = response.json()
response.raise_for_status()

Body fields

Legacy names (still work; when both spellings are sent, the new one wins):

Send Content-Type: application/json (the media type is read in any case). Keys the endpoint does not read, quantity and every price field included, are ignored and listed in the warnings of the response as ignored_field.

Which package may I send?

The topup is priced from the list that step 1 returned for this ICCID, so package_id must come from that list. A package that is not in it is refused with 404 not_found ("Package ... not found or has no valid price"), and nothing is debited. Should you get that answer for a package you have just received (for example right after FX-Port was updated), ask for the list again with force=true and send the topup again.

Response example

A sandbox topup. The response has status 200, not 201.

{
  "environment": "sandbox",
  "success": true,
  "data": {
    "topup": {
      "code": "20261101-106853",
      "order_id": "20261101-106853",
      "package_id": "france-in-7days-1gb-topup",
      "package": "KPN France Data only-1 GB - 7 days",
      "data": "1 GB",
      "validity": 7,
      "price": 468.84,
      "currency": "DZD",
      "total_price": 468.84,
      "retail_price": 468.84,
      "agency_currency": "DZD",
      "supplier_currency": "USD",
      "exchange_rate": 250.0
    },
    "iccid": "8900000540463077957",
    "balance": { "previous": 0.0, "current": 0.0, "currency": "DZD" }
  },
  "booking_id": "FX-1793546625391",
  "message": "eSIM topup completed successfully",
  "balanceDebited": false,
  "transactionCreated": false,
  "payoutCreated": false,
  "balance_debited": false,
  "transaction_created": false,
  "payout_created": false
}

In the sandbox

A sandbox topup is accepted by the supplier's test system and debits nothing: balance is 0.0 before and after, and the three flags are false. The usage of a sandbox eSIM does not change after a topup. The balance check and the duplicate check run on live only.

Does a topup extend or replace the current plan?

A topup adds the package's data allowance to the eSIM: it does not replace or shorten what the traveler already has. How the validity changes depends on the package, so FX-Port does not predict it. Read the result from eSIM usage after the topup (remaining, total and expired_at), with force=true, because usage is cached for 15 minutes.

Duplicates and retries

There is no idempotency key. A second topup is refused with 409 duplicate_request while an identical one (same eSIM and package) is being processed, and on live also when a topup for the same eSIM was created in the last 60 seconds, whatever the package (existing_booking_id names it). If a call times out, look at topup history before you send it again.

Errors

Step 1 answers 400 invalid_iccid or invalid_locale, 404 iccid_not_found, and 503 service_unavailable when the supplier cannot be reached. When the supplier refuses the lookup, the answer has the supplier's status (for example 429).