Skip to content
FX-Port/Docs
GuidesAPI referenceChangelog
Get API keys
  • Overview
  • Error object

Catalog

  • PackagesGET
  • Compatible devicesGET

Orders and top-ups

  • Create an orderPOST
  • Top-up packagesGET
  • Top upPOST

After the order

  • UsageGET
  • Usage of several eSIMsGET
  • BookingsGET
  • Top-up historyGET
  • Check ownershipGET
  • Setup dataGET
  • Installation instructionsGET

Objects

  • eSIM package
  • eSIM booking

eSIMs ยท Catalog

List eSIM packages

List the eSIM packages your agency can sell, with prices in your agency currency.

GET/api/v1/esims/packages

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

Filter by country (a slug such as france). The unfiltered catalog is about 4 MB, has no pagination and is the slowest call of the eSIM API, so send country whenever you can and accept compressed responses. English text is served from a cache that is refreshed about every 50 minutes. Another locale is fetched from the supplier on its first call (about 10 seconds) and then cached for an hour.

Regional and worldwide bundles are global packages whose country_slug is the region (for example europe). A 202 means the catalog is still loading after a restart: wait a few seconds and send the call again.

Four amounts describe each package: base_price, retail_price, balance_debit_amount and agency_commission. Read the pricing guide before you compute anything from them.

curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
Response200
{
  "environment": "sandbox",
  "success": true,
  "endpoint": "/packages",
  "data": [
    {
      "id": "france-in-7days-1gb",
      "package_id": "france-in-7days-1gb",
      "type": "sim",
      "price": 402.5,
      "base_price": 402.5,
      "amount": 1024,
      "day": 7,
      "is_unlimited": false,
      "title": "1 GB - 7 days",
      "is_fair_usage_policy": false,
      "fair_usage_policy": null,
      "data": "1 GB",
      "voice": null,
      "text": null,
      "country_name": "France",
      "country_code": "FR",
      "country_slug": "france",
      "country_image_url": "https://cdn-revamp.airalo.com/images/9753dedb-d495-47cf-b6e4-82e555564743.png",
      "operator_name": "KPN France Data only",
      "operator_id": 1704,
      "operator_style": "dark",
      "operator_gradient_start": "#F1D4FB",
      "operator_gradient_end": "#EEC0FF",
      "operator_type": "local",
      "operator_is_prepaid": false,
      "operator_esim_type": "Prepaid",
      "operator_warning": null,
      "operator_apn_type": "automatic",
      "operator_is_roaming": true,
      "operator_info": [
        "Data-only eSIM.",
        "Rechargeable online with no expiry."
      ],
      "operator_image_url": "https://cdn-revamp.airalo.com/images/01b47d41-fbb4-4032-8f5a-d1ca6a0f3688.png",
      "operator_plan_type": "data",
      "operator_activation_policy": "first-usage",
      "operator_is_kyc_verify": false,
      "operator_rechargeability": true,
      "operator_other_info": "Covers metropolitan (mainland) France and Corsica. Does not include overseas territories (Guadeloupe, Martinique, Reunion, ...",
      "operator_coverages": [
        {
          "name": "FR",
          "code": "FR",
          "networks": [
            {
              "name": "Orange",
              "types": [
                "5G"
              ]
            }
          ]
        }
      ],
      "operator_apn": {
        "ios": {
          "apn_type": "automatic",
          "apn_value": null
        },
        "android": {
          "apn_type": "automatic",
          "apn_value": null
        }
      },
      "is_regional": false,
      "is_global": false,
      "retail_price": 468.84,
      "total_price": 468.84,
      "balance_debit_amount": 418.6,
      "b2b_price": 418.6,
      "agency_commission": "12 %",
      "commission_rate": 12,
      "currency": "DZD",
      "supplier_currency": "USD",
      "exchange_rate": 250
    },
    {
      "id": "france-in-15days-2gb",
      "package_id": "france-in-15days-2gb",
      "type": "sim",
      "price": 547.5,
      "base_price": 547.5,
      "amount": 2048,
      "day": 15,
      "is_unlimited": false,
      "title": "2 GB - 15 days",
      "is_fair_usage_policy": false,
      "fair_usage_policy": null,
      "data": "2 GB",
      "voice": null,
      "text": null,
      "country_name": "France",
      "country_code": "FR",
      "country_slug": "france",
      "country_image_url": "https://cdn-revamp.airalo.com/images/9753dedb-d495-47cf-b6e4-82e555564743.png",
      "operator_name": "KPN France Data only",
      "operator_id": 1704,
      "operator_style": "dark",
      "operator_gradient_start": "#F1D4FB",
      "operator_gradient_end": "#EEC0FF",
      "operator_type": "local",
      "operator_is_prepaid": false,
      "operator_esim_type": "Prepaid",
      "operator_warning": null,
      "operator_apn_type": "automatic",
      "operator_is_roaming": true,
      "operator_info": [
        "Data-only eSIM.",
        "Rechargeable online with no expiry."
      ],
      "operator_image_url": "https://cdn-revamp.airalo.com/images/01b47d41-fbb4-4032-8f5a-d1ca6a0f3688.png",
      "operator_plan_type": "data",
      "operator_activation_policy": "first-usage",
      "operator_is_kyc_verify": false,
      "operator_rechargeability": true,
      "operator_other_info": "Covers metropolitan (mainland) France and Corsica. Does not include overseas territories (Guadeloupe, Martinique, Reunion, ...",
      "operator_coverages": [
        {
          "name": "FR",
          "code": "FR",
          "networks": [
            {
              "name": "Orange",
              "types": [
                "5G"
              ]
            }
          ]
        }
      ],
      "operator_apn": {
        "ios": {
          "apn_type": "automatic",
          "apn_value": null
        },
        "android": {
          "apn_type": "automatic",
          "apn_value": null
        }
      },
      "is_regional": false,
      "is_global": false,
      "retail_price": 637.73,
      "total_price": 637.73,
      "balance_debit_amount": 569.4,
      "b2b_price": 569.4,
      "agency_commission": "12 %",
      "commission_rate": 12,
      "currency": "DZD",
      "supplier_currency": "USD",
      "exchange_rate": 250
    }
  ],
  "meta": {
    "total_packages": 12,
    "filters_applied": {
      "country": "france",
      "type": "local"
    },
    "locale": "en",
    "agency_currency": "DZD",
    "currency": "DZD",
    "supplier_currency": "USD",
    "exchange_rate": 250,
    "commission_percentage": "12 %",
    "commission_rate": 12
  }
}
Response202
{
  "environment": "sandbox",
  "success": false,
  "message": "No cached packages available. Package fetcher may still be loading initial data.",
  "data": [],
  "meta": {}
}

Request

Query parameters

countrystring

Country slug, for example france or turkey. Regions have their own slug, for example europe. A country name as people write it is read as its slug (United States is united-states, Bosnia & Herzegovina is bosnia-and-herzegovina); case and accents do not matter. An unknown slug or a name that matches no slug returns an empty list.

At most 64 characters.

typestring

Scope of the package: local is one country, global is every regional and worldwide bundle. Any other well-formed value returns an empty list: there is no regional value.

At most 32 characters.

filter[type]stringdeprecated

Legacy name, still accepted. Use type instead.

Previous name of type. It still works and the response carries a deprecated_field warning.

At most 32 characters.

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 packages that match the filters.

successboolean

true when the catalog was returned.

endpointstring

The route that answered, /packages.

dataarray of EsimPackage

The packages that match the filters. Not paginated: filter by country.

See the eSIM package object

metaobject

Facts about the catalog response.

ShowHide 9 attributes
total_packagesinteger

Number of packages in data, after the filters.

filters_appliedobject

The filters the request applied.

ShowHide 2 attributes
countrystringnullable

The country filter, or null.

typestringnullable

The type filter, or null.

localestring

Language used for the text fields of this response.

agency_currencystringdeprecated

Legacy name, still accepted. Use currency instead.

Currency of every amount: the settlement currency of your agency. The older name of currency: same value, use currency.

currencystring

Currency of every amount: the settlement currency of your agency. The snake_case twin of agency_currency, with the same value: use this name.

supplier_currencystring

Currency the supplier prices packages in.

exchange_ratenumber

Rate used to convert supplier_currency to your agency currency.

commission_percentagestring

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.

202The catalog is still loading after a restart. success is false and data is empty: retry in a few seconds.

successboolean

Always false: the data is not available yet.

messagestring

What is missing and that it is still loading.

dataarray of object

Always empty.

metaobject

Empty for a catalog that is loading.

Errors

StatusCodeExample message
400invalid_countrycountry must be a country slug such as france (received 'France!').
400invalid_localelocale must be a language code such as en, fr or ar (received '12').

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

Related guides

  • Package catalog
  • eSIM pricing
PreviousCancel a confirmed hotel bookingNext List eSIM compatible devices

ยฉ 2026 FX-Port

TermsPrivacy[email protected]