# List eSIM packages

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

Endpoint: `GET /esims/packages`

Source: https://fx-port.com/docs/api/list-esim-packages

`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.

## Request

### Query parameters

- `country` (string, optional): 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.
- `type` (string, optional): 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]` (string, deprecated, optional): Legacy name: use `type`. Previous name of `type`. It still works and the response carries a `deprecated_field` warning. At most 32 characters.
- `locale` (string, optional): 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.

### Example request

```bash
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
```

## Response

### 200: The packages that match the filters.

- `success` (boolean): `true` when the catalog was returned.
- `endpoint` (string): The route that answered, `/packages`.
- `data` (array of EsimPackage): The packages that match the filters. Not paginated: filter by `country`.
- `meta` (object): Facts about the catalog response.
  - `total_packages` (integer): Number of packages in `data`, after the filters.
  - `filters_applied` (object): The filters the request applied.
    - `country` (string, nullable): The `country` filter, or null.
    - `type` (string, nullable): The `type` filter, or null.
  - `locale` (string): Language used for the text fields of this response.
  - `agency_currency` (string, deprecated): Legacy name: use `currency`. Currency of every amount: the settlement currency of your agency. The older name of `currency`: same value, use `currency`.
  - `currency` (string): 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_currency` (string): Currency the supplier prices packages in.
  - `exchange_rate` (number): Rate used to convert `supplier_currency` to your agency currency.
  - `commission_percentage` (string): Your commission rate as text, for example `12 %`.
  - `commission_rate` (number): Your commission rate as a number: `12` for a standard agency, `0` for a contracted corporate agency.

```json
{
  "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
  }
}
```

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

- `success` (boolean): Always `false`: the data is not available yet.
- `message` (string): What is missing and that it is still loading.
- `data` (array of object): Always empty.
- `meta` (object): Empty for a catalog that is loading.

```json
{
  "environment": "sandbox",
  "success": false,
  "message": "No cached packages available. Package fetcher may still be loading initial data.",
  "data": [],
  "meta": {}
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_country` | country must be a country slug such as france (received 'France!'). |
| 400 | `invalid_locale` | locale must be a language code such as en, fr or ar (received '12'). |

See [Errors](https://fx-port.com/docs/errors.md) for every code and how to react.

## Related guides

- [Package catalog](https://fx-port.com/docs/esims/packages.md)
- [eSIM pricing](https://fx-port.com/docs/esims/pricing.md)