# List topup packages of an eSIM

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

Endpoint: `GET /esims/topup-packages/{iccid}`

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

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

## Request

### Path parameters

- `iccid` (string, required): The eSIM to top up. It must be an eSIM that your agency ordered.

### Query parameters

- `force` (boolean, optional): Skip the five-minute cache and ask the supplier again. An empty value means not sent. Default `false`.
- `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/topup-packages/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
```

## Response

### 200: The topup packages of the eSIM.

- `success` (boolean): `true` when the list was returned.
- `data` (object): Wrapper object: the list is `data.data`.
  - `data` (array of object): The packages that can top up this eSIM. Empty when it cannot be topped up.
    - `id` (string, deprecated): Legacy name: use `package_id`. 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_id` (string): 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.
    - `type` (string): Always `topup`.
    - `price` (number): The price to charge the traveler, in your agency currency. Same as `total_price`. Here `price` is the retail amount, unlike the catalog.
    - `amount` (integer): Data allowance in megabytes. `0` means unlimited.
    - `day` (integer): Validity in days.
    - `is_unlimited` (boolean): `true` for unlimited-data packages.
    - `title` (string): Label of the package, in the language of the request.
    - `data` (string): Data allowance as text, for example `1 GB`.
    - `short_info` (string, nullable): A short note about the package. Usually null.
    - `voice` (integer, nullable): Voice minutes included, or null.
    - `text` (integer, nullable): SMS included, or null.
    - `prices` (object): Reference prices published by the supplier.
      - `recommended_retail_price` (object): The supplier's recommended retail price in many currencies, by currency code. For reference only: it is not what you are charged.
    - `base_price` (number): Base price in your agency currency, before your commission. Same meaning as `price` in the catalog.
    - `commission` (number): Your commission as an amount, in your agency currency.
    - `total_price` (number): The price to charge the traveler, in your agency currency.
    - `retail_price` (number): The price to charge the traveler, in your agency currency. Another name of `total_price`, with the same value.
    - `balance_debit_amount` (number, deprecated): Legacy name: use `b2b_price`. The amount debited from your agency balance when you create this topup. The older name of `b2b_price`: same value, use `b2b_price`.
    - `b2b_price` (number): 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_commission` (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.
    - `currency` (string): Currency of every amount: the settlement currency of your agency.
    - `supplier_currency` (string): Currency the supplier prices the package in.
- `cached` (boolean): `true` when the list comes from the five-minute cache. Absent on a fresh answer.
- `cache_age_seconds` (integer): Age of the cached list in seconds. Present with `cached`.

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

## 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 |

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

## Related guides

- [Top up an eSIM](https://fx-port.com/docs/esims/topups.md)
- [Supplier continuity](https://fx-port.com/docs/esims/supplier-continuity.md)