Package catalog

List packages

GET /api/v1/esims/packages

Returns the cached package catalog with pricing computed for your agency. Results are cached server-side and refreshed periodically, so repeated calls are cheap.

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

Query parameters

Parameter	Description
`country`	Filter by country slug (e.g. `france`, `turkey`)
`filter[type]`	Filter by package type (e.g. `local`, `regional`, `global`)
`locale`	Language for package text fields (`en`, `fr`, `ar`, …). Falls back to `Accept-Language`, then `en`

curl --request GET \
  --url 'https://api.fx-port.com/api/v1/esims/packages?country=france&filter%5Btype%5D=local&locale=en' \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY'

Response example

Example response for GET /api/v1/esims/packages?locale=en (one package shown):

{
  "environment": "sandbox",
  "success": true,
  "endpoint": "/packages",
  "data": [
    {
      "id": "change-in-3days-unlimited",
      "type": "sim",
      "price": 1812.5,
      "amount": 0,
      "day": 3,
      "is_unlimited": true,
      "title": "Unlimited - 3 days",
      "is_fair_usage_policy": 1,
      "fair_usage_policy": "Lower speed rate of 1 Mbps after 3 GB usage per day.",
      "data": "Unlimited",
      "voice": null,
      "text": null,
      "country_name": "United States",
      "country_code": "US",
      "country_slug": "united-states",
      "country_image_url": "https://cdn-revamp.airalo.com/images/ad19c2a2-40b8-4dac-b95e-269703c8561b.png",
      "operator_name": "Change",
      "operator_id": 1181,
      "operator_style": "light",
      "operator_gradient_start": "#0f1b3f",
      "operator_gradient_end": "#194281",
      "operator_type": "local",
      "operator_is_prepaid": false,
      "operator_esim_type": "Prepaid",
      "operator_warning": null,
      "operator_apn_type": "manual",
      "operator_is_roaming": true,
      "operator_info": [
        "5G Data-only eSIM.",
        "Rechargeable online with no expiry.",
        "Operates on T-Mobile, Verizon, and U.S. Cellular networks in the United States of America."
      ],
      "operator_image_url": "https://cdn-revamp.airalo.com/images/6bf8859b-3f43-41c7-ac54-434e2534813c.png",
      "operator_plan_type": "data",
      "operator_activation_policy": "first-usage",
      "operator_is_kyc_verify": false,
      "operator_rechargeability": true,
      "operator_other_info": "This eSIM is for travelers to the United States. eSIM covers the United States, including Hawaii and Puerto Rico, with limited availability in Alaska",
      "operator_coverages": [
        {
          "name": "US",
          "code": "US",
          "networks": [
            { "name": "T-Mobile", "types": ["5G"] },
            { "name": "Verizon", "types": ["5G"] }
          ]
        }
      ],
      "operator_apn": {
        "ios": { "apn_type": "automatic", "apn_value": "wbdata" },
        "android": { "apn_type": "manual", "apn_value": "wbdata" }
      },
      "is_regional": false,
      "is_global": false,
      "retail_price": 2111.2,
      "total_price": 2111.2,
      "balance_debit_amount": 1885.0,
      "agency_commission": "12 %",
      "currency": "DZD",
      "supplier_currency": "USD",
      "exchange_rate": 250.0
    }
  ],
  "meta": {
    "total_packages": 1,
    "filters_applied": { "country": null, "type": null },
    "locale": "en",
    "agency_currency": "DZD",
    "supplier_currency": "USD",
    "exchange_rate": 250.0,
    "commission_percentage": "12 %"
  }
}

Save id from the response — it's what you pass as package_id when creating an order.

Response field reference

Package identity and data allowance

Field	Type	Meaning
`id`	string	Package identifier — pass as `package_id` when creating an order
`type`	string	Package/product type as sold, e.g. `sim`
`title`	string	Human-readable package label (data amount + validity)
`data`	string	Data allowance for the package, e.g. `"1 GB"` or `"Unlimited"`
`amount`	number	Data allowance in MB. `0` means unlimited — check `is_unlimited` rather than treating `0` as "no data"
`is_unlimited`	boolean	`true` for unlimited-data packages
`is_fair_usage_policy`	boolean/number	Truthy when an unlimited package throttles speed after a threshold — read `fair_usage_policy` for the exact terms
`fair_usage_policy`	string \| null	Human-readable fair-usage terms (e.g. throttle speed and daily threshold) when `is_fair_usage_policy` is truthy
`day`	number	Validity in days from activation
`voice`	string \| null	Voice minutes included, when the package bundles voice (`null` = data-only)
`text`	string \| null	SMS included, when the package bundles SMS (`null` = data-only)
`is_regional`	boolean	`true` if this package covers a defined multi-country region
`is_global`	boolean	`true` if this package covers global/worldwide destinations

Country

Field	Type	Meaning
`country_name`	string	Destination country, human-readable
`country_code`	string	Destination country, ISO 3166-1 alpha-2
`country_slug`	string	Destination country slug — pass as the `country` query parameter
`country_image_url`	string	Flag/country image URL for display

Operator (underlying mobile network)

Field	Type	Meaning
`operator_name`	string	Underlying mobile network operator/brand for this package
`operator_id`	number	Internal operator identifier
`operator_type`	string	Package scope: `local` (one country), `regional`, or `global`
`operator_style` / `operator_gradient_start` / `operator_gradient_end`	string	Display styling hints (light/dark theme, gradient colors) for this operator's branding
`operator_is_prepaid`	boolean	Whether the underlying plan is prepaid
`operator_esim_type`	string	e.g. `Prepaid`
`operator_warning`	string \| null	Operator-specific caution to show travelers (e.g. topup window), when applicable
`operator_apn_type`	string	`automatic` or `manual` — whether APN settings are auto-configured
`operator_is_roaming`	boolean	Whether this package operates via roaming rather than a local SIM profile
`operator_info`	string[]	Short bullet facts about the operator/network (technology, rechargeability, coverage)
`operator_image_url`	string	Operator logo URL
`operator_plan_type`	string	e.g. `data` (data-only plan)
`operator_activation_policy`	string	When validity starts, e.g. `first-usage` (starts on first connection, not purchase)
`operator_is_kyc_verify`	boolean	Whether the destination country requires identity verification for this operator (rare; relevant for a few countries)
`operator_rechargeability`	boolean	Whether this ICCID can be topped up — see Top up an eSIM
`operator_other_info`	string	Longer free-text coverage notes/exclusions (e.g. territories not covered)
`operator_coverages`	array	Per-country network list: `{ name, code, networks: [{ name, types }] }`
`operator_apn`	object	Manual APN settings per platform: `{ ios: { apn_type, apn_value }, android: { apn_type, apn_value } }`

Pricing — see eSIM pricing for the full formula

Field	Type	Meaning
`price`	number	FX-Port's B2B price in your agency currency
`retail_price` / `total_price`	number	`price` + your agency commission — what you charge the traveler
`balance_debit_amount`	number	Amount actually debited from your agency balance if you order this package
`agency_commission`	string	Commission rate applied, as text (`"12 %"`, or `"0 %"` for corporate agencies)
`currency`	string	Your agency's settlement currency
`supplier_currency`	string	Currency the fulfilling supplier settles in
`exchange_rate`	number	`supplier_currency` → `currency` rate used for this package

`meta` field reference

Field	Meaning
`total_packages`	Number of packages in `data` after filtering
`filters_applied`	Echo of the `country` / `type` filters actually applied
`locale`	Language used for text fields in this response
`agency_currency`	Same as `currency` on each package — your agency's settlement currency
`supplier_currency`	Same as `supplier_currency` on each package
`exchange_rate`	Same as `exchange_rate` on each package
`commission_percentage`	The commission rate applied across this response

Compatible devices

GET /api/v1/esims/compatible-devices

Returns the cached list of devices known to support eSIM, useful for pre-sale device checks before a traveler purchases a package.

curl --request GET \
  --url https://api.fx-port.com/api/v1/esims/compatible-devices \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY'

Response example

{
  "success": true,
  "data": [
    { "brand": "ASUS", "model": "AI2501", "name": "ASUS Zenfone 12 Ultra", "os": "android" },
    { "brand": "Alcatel", "model": "T803D", "name": "V3 Ultra", "os": "android" },
    { "brand": "Apple", "model": "iPhone15,2", "name": "iPhone 14 Pro", "os": "ios" }
  ]
}

Response field reference

Field	Meaning
`brand`	Device manufacturer
`model`	Manufacturer's internal model identifier
`name`	Human-readable marketing name for the device
`os`	Operating system family: `ios` or `android`

This list can return "success": false with an empty data array for a brief moment while the device cache is still loading in the background right after a deployment — retry after a few seconds.

Package catalog

On this page