# List eSIM bookings

> List the eSIM orders of your agency in this environment, newest first, with search and pagination.

Endpoint: `GET /esims/bookings`

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

`GET /api/v1/esims/bookings`

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

Only orders (`type` `esim`) are listed: topups are returned by `GET /esims/bookings/{iccid}/topup-history`, and both are listed by the account history. A failed attempt is listed with the status `failed`.

`search` matches part of the booking id, the traveler's first or last name, the email, the package name or the ICCID (not the supplier order code or the phone). Characters that are not letters, digits or `@.-_+':/&` are treated as spaces, so any text is safe. `pagination.total` counts the bookings that match, `search` included.

An API key gets at most 200 bookings per request: `all=true` returns pages of 200 (follow `pagination.has_more` and `page`) and the response carries a `coerced_value` warning.

## Request

### Query parameters

- `search` (string, optional): Part of a booking id, name, email, package name or ICCID. At most 100 characters. At most 100 characters.
- `page` (integer, optional): The page, starting at 1. An empty value means not sent. Between 1 and 10000. Default `1`.
- `limit` (integer, optional): Bookings per page, from 1 to 200. An empty value means not sent. Between 1 and 200. Default `50`.
- `all` (boolean, optional): `true` for pages of 200 bookings (the default `limit` becomes 200). An empty value means not sent. Default `false`.

### Example request

```bash
curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
```

## Response

### 200: A page of eSIM bookings.

- `success` (boolean): `true` when the list was returned.
- `data` (array of EsimBooking): The eSIM orders of this page, newest first. Topups are not listed here.
- `pagination` (object): Where this page sits in the list.
  - `total` (integer): Number of eSIM bookings of your agency in this environment that match the request (`search` included).
  - `page` (integer): The page returned.
  - `limit` (integer): The page size used. With `all=true` for the dashboard it equals `total`.
  - `pages` (integer, deprecated): Legacy name: use `total_pages`. Number of pages: `total` divided by `limit`, rounded up. `0` when there are no bookings.
  - `total_pages` (integer): Number of pages: `total` divided by `limit`, rounded up. `0` when there are no bookings.
  - `has_more` (boolean): `true` when another page follows.

```json
{
  "environment": "sandbox",
  "success": true,
  "data": [
    {
      "id": "639417b4-b103-4ece-bd5d-850315322278",
      "booking_id": "FX-1793546602916",
      "order_id": "20261101-106852",
      "status": "confirmed",
      "currency": "DZD",
      "total_price": 468.84,
      "agency_commission": 50.24,
      "type": "esim",
      "package_name": "1 GB - 7 days • France",
      "iccid": "8900000540463077957",
      "customer_email": "traveler@example.com",
      "customer_first_name": "John",
      "customer_last_name": "Smith",
      "customer_phone": "+15555550123",
      "provider_name": "Airalo",
      "supplier_id": "airalo",
      "created_at": "2026-11-01T15:23:22.961228+00:00",
      "updated_at": "2026-11-01T15:23:22.961228+00:00",
      "environment": "sandbox"
    }
  ],
  "pagination": {
    "total": 61,
    "page": 1,
    "limit": 1,
    "pages": 61,
    "total_pages": 61,
    "has_more": true
  }
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_search` | search must be at most 100 characters. |
| 422 | `validation_error` | Input should be less than or equal to 200 |

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

## Related guides

- [eSIM bookings](https://fx-port.com/docs/esims/bookings.md)