eSIMs · Orders and top-ups

List topup packages of an eSIM

List the packages that can top up one eSIM of your agency, with prices in your agency currency.

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

Requires an API key with Read permission; a Read+Write key works too.

Always call this before you create a topup: the packages depend on the eSIM, and the package_id you send to POST /esims/topups must come from this list. An empty data.data means the eSIM cannot be topped up.

The list is cached for five minutes per eSIM and language (cached and cache_age_seconds say so). force=true skips the cache. In the topup list price is the retail amount; the amount that is debited is balance_debit_amount.

curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"

Response200

{
  "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"
      },
      {
        "id": "france-in-15days-2gb-topup",
        "package_id": "france-in-15days-2gb-topup",
        "type": "topup",
        "price": 637.73,
        "amount": 2048,
        "day": 15,
        "is_unlimited": false,
        "title": "2 GB - 15 days",
        "data": "2 GB",
        "short_info": null,
        "voice": null,
        "text": null,
        "prices": {
          "recommended_retail_price": {
            "EUR": 5.34,
            "GBP": 4.5,
            "USD": 6
          }
        },
        "base_price": 547.5,
        "commission": 68.33,
        "total_price": 637.73,
        "retail_price": 637.73,
        "balance_debit_amount": 569.4,
        "b2b_price": 569.4,
        "agency_commission": "12 %",
        "commission_rate": 12,
        "currency": "DZD",
        "supplier_currency": "USD"
      }
    ]
  }
}

Request

Path parameters

iccidstringrequired

The eSIM to top up. It must be an eSIM that your agency ordered.

Query parameters

forceboolean

Skip the five-minute cache and ask the supplier again. An empty value means not sent.

Default false.

localestring

Language of the text fields. Without it the Accept-Language header is used, then en. Any spelling of a locale is read and only its language counts: fr, fr-CA, zh-Hans, pt_BR, fr_FR.UTF-8, or a whole Accept-Language value such as fr-FR,fr;q=0.9 (the first language is used). Supported: en, fr, ar, de, es, it, ja, ko, pl, pt, ro, ru, sq, tr, vi, zh. Another well-formed language is answered in English and the response carries a coerced_value warning.

At most 80 characters.

Response

200The topup packages of the eSIM.

successboolean

true when the list was returned.

dataobject

Wrapper object: the list is data.data.

ShowHide 1 attribute

dataarray of object

The packages that can top up this eSIM. Empty when it cannot be topped up.

ShowHide 23 attributes

idstringdeprecated

Legacy name, still accepted. Use package_id instead.

Topup package id. Send it as package_id when you create the topup. The older name of package_id: same value, use package_id.

package_idstring

Topup package id. Send it as package_id when you create the topup. The snake_case twin of id, with the same value: use this name.

typestring

Always topup.

pricenumber

The price to charge the traveler, in your agency currency. Same as total_price. Here price is the retail amount, unlike the catalog.

amountinteger

Data allowance in megabytes. 0 means unlimited.

dayinteger

Validity in days.

is_unlimitedboolean

true for unlimited-data packages.

titlestring

Label of the package, in the language of the request.

datastring

Data allowance as text, for example 1 GB.

short_infostringnullable

A short note about the package. Usually null.

voiceintegernullable

Voice minutes included, or null.

textintegernullable

SMS included, or null.

pricesobject

Reference prices published by the supplier.

ShowHide 1 attribute

recommended_retail_priceobject

The supplier's recommended retail price in many currencies, by currency code. For reference only: it is not what you are charged.

base_pricenumber

Base price in your agency currency, before your commission. Same meaning as price in the catalog.

commissionnumber

Your commission as an amount, in your agency currency.

total_pricenumber

The price to charge the traveler, in your agency currency.

retail_pricenumber

The price to charge the traveler, in your agency currency. Another name of total_price, with the same value.

balance_debit_amountnumberdeprecated

Legacy name, still accepted. Use b2b_price instead.

The amount debited from your agency balance when you create this topup. The older name of b2b_price: same value, use b2b_price.

b2b_pricenumber

The amount debited from your agency balance when you create this topup. The snake_case twin of balance_debit_amount, with the same value: use this name.

agency_commissionstring

Your commission rate as text, for example 12 %.

commission_ratenumber

Your commission rate as a number: 12 for a standard agency, 0 for a contracted corporate agency.

currencystring

Currency of every amount: the settlement currency of your agency.

supplier_currencystring

Currency the supplier prices the package in.

cachedboolean

true when the list comes from the five-minute cache. Absent on a fresh answer.

cache_age_secondsinteger

Age of the cached list in seconds. Present with cached.

Errors

Status	Code	Example message
400	`invalid_iccid`	iccid must be 18-22 digits (received '123').
404	`iccid_not_found`	No eSIM with this ICCID was found for your account.
503	`service_unavailable`	Airalo token unavailable

The shape of the error body depends on the endpoint. See Errors for every shape and code.

{ "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" }, { "id": "france-in-15days-2gb-topup", "package_id": "france-in-15days-2gb-topup", "type": "topup", "price": 637.73, "amount": 2048, "day": 15, "is_unlimited": false, "title": "2 GB - 15 days", "data": "2 GB", "short_info": null, "voice": null, "text": null, "prices": { "recommended_retail_price": { "EUR": 5.34, "GBP": 4.5, "USD": 6 } }, "base_price": 547.5, "commission": 68.33, "total_price": 637.73, "retail_price": 637.73, "balance_debit_amount": 569.4, "b2b_price": 569.4, "agency_commission": "12 %", "commission_rate": 12, "currency": "DZD", "supplier_currency": "USD" } ] } }

Request

Path parameters

iccidstringrequired

The eSIM to top up. It must be an eSIM that your agency ordered.

Query parameters

forceboolean

Skip the five-minute cache and ask the supplier again. An empty value means not sent.

Default false.

localestring

At most 80 characters.

Response

200The topup packages of the eSIM.

successboolean

true when the list was returned.

dataobject

Wrapper object: the list is data.data.

ShowHide 1 attribute

dataarray of object

The packages that can top up this eSIM. Empty when it cannot be topped up.

ShowHide 23 attributes

idstringdeprecated

Legacy name, still accepted. Use package_id instead.

Topup package id. Send it as package_id when you create the topup. The older name of package_id: same value, use package_id.

package_idstring

Topup package id. Send it as package_id when you create the topup. The snake_case twin of id, with the same value: use this name.

typestring

Always topup.

pricenumber

The price to charge the traveler, in your agency currency. Same as total_price. Here price is the retail amount, unlike the catalog.

amountinteger

Data allowance in megabytes. 0 means unlimited.

dayinteger

Validity in days.

is_unlimitedboolean

true for unlimited-data packages.

titlestring

Label of the package, in the language of the request.

datastring

Data allowance as text, for example 1 GB.

short_infostringnullable

A short note about the package. Usually null.

voiceintegernullable

Voice minutes included, or null.

textintegernullable

SMS included, or null.

pricesobject

Reference prices published by the supplier.

ShowHide 1 attribute

recommended_retail_priceobject

The supplier's recommended retail price in many currencies, by currency code. For reference only: it is not what you are charged.

base_pricenumber

Base price in your agency currency, before your commission. Same meaning as price in the catalog.

commissionnumber

Your commission as an amount, in your agency currency.

total_pricenumber

The price to charge the traveler, in your agency currency.

retail_pricenumber

The price to charge the traveler, in your agency currency. Another name of total_price, with the same value.

balance_debit_amountnumberdeprecated

Legacy name, still accepted. Use b2b_price instead.

The amount debited from your agency balance when you create this topup. The older name of b2b_price: same value, use b2b_price.

b2b_pricenumber

The amount debited from your agency balance when you create this topup. The snake_case twin of balance_debit_amount, with the same value: use this name.

agency_commissionstring

Your commission rate as text, for example 12 %.

commission_ratenumber

Your commission rate as a number: 12 for a standard agency, 0 for a contracted corporate agency.

currencystring

Currency of every amount: the settlement currency of your agency.

supplier_currencystring

Currency the supplier prices the package in.

cachedboolean

true when the list comes from the five-minute cache. Absent on a fresh answer.

cache_age_secondsinteger

Age of the cached list in seconds. Present with cached.

Status

Code

Example message

400

invalid_iccid

iccid must be 18-22 digits (received '123').

404

iccid_not_found

No eSIM with this ICCID was found for your account.

503

service_unavailable

Airalo token unavailable

Request

Path parameters

Query parameters

Response

Errors

Related guides

Request

Path parameters

Query parameters

Response

Errors

Related guides