# List booking history > List the bookings of your agency across flights, hotels, eSIMs and transfers, newest first, as short summaries. Endpoint: `GET /history` Source: https://fx-port.com/docs/api/list-booking-history `GET /api/v1/history` Requires an API key with **Read** permission; a **Read+Write** key works too. Use it for status tracking, reconciliation and dashboards, and `GET /bookings/{booking_id}` for one booking in full. The list is limited to the environment of your key. eSIM orders and topups are both listed (`type` tells them apart). `pagination.total` counts the bookings that match. Each product contributes at most its 200 newest bookings to the pages, so at most 800 can be reached with `product=all`: follow `has_more`, and narrow the list with `date_from` and `date_to` to reach older bookings. `status` is an exact match on the status of the booking, in any case; spaces and hyphens are read as underscores (`On Hold` is `on_hold`). `pending` is accepted as another name of `awaiting_payment`, a held flight that is not paid. An unknown status returns an empty list. ## Request ### Query parameters - `product` (string, optional): Keep one product. Case does not matter. The singular names (`flight`, `hotel`, `esim`, `transfer`) are read as the plural. One of `all`, `esims`, `flights`, `hotels`, `transfers`. Default `all`. - `status` (string, optional): Keep bookings with this status, for example `confirmed`, `awaiting_payment` (or `pending`), `cancelled`, `failed`, `refunded`. Case does not matter; spaces and hyphens are read as underscores (`On Hold` is `on_hold`). At most 32 characters. At most 32 characters. - `date_from` (string, optional): Inclusive start. Any ISO 8601 spelling is read: a date (`2026-07-01` or `20260701`, taken as 00:00:00 UTC) or a datetime (`2026-07-01T10:30:00Z`) with 1 to 9 fraction digits and an offset written `Z`, `+01:00` or `+0100`. A datetime without an offset is read as UTC. Years 1900 to 2200. In a URL write a `+` as `%2B`. At most 40 characters. - `date_to` (string, optional): Inclusive end, in the same spellings as `date_from`. A bare date means the end of that day (23:59:59.999999 UTC). It must not be before `date_from`. At most 40 characters. - `from` (string, deprecated, optional): Legacy name: use `date_from`. Previous name of `date_from`. It still works, with the same spellings, and the response carries a `deprecated_field` warning. At most 40 characters. - `from_date` (string, deprecated, optional): Legacy name: use `date_from`. Previous name of `date_from`. It still works, with the same spellings, and the response carries a `deprecated_field` warning. At most 40 characters. - `to` (string, deprecated, optional): Legacy name: use `date_to`. Previous name of `date_to`. It still works, with the same spellings, and the response carries a `deprecated_field` warning. At most 40 characters. - `to_date` (string, deprecated, optional): Legacy name: use `date_to`. Previous name of `date_to`. It still works, with the same spellings, and the response carries a `deprecated_field` warning. At most 40 characters. - `page` (integer, optional): The page, starting at 1 (at most 10000). An empty value means not sent. Between 1 and 10000. Default `1`. - `limit` (integer, optional): Entries per page, from 1 to 100. An empty value means not sent. Between 1 and 100. Default `20`. ### Example request ```bash curl 'https://api.fx-port.com/api/v1/history?product=esims&limit=2' \ -H "Authorization: Bearer fxp_test_YOUR_KEY" ``` ## Response ### 200: A page of booking summaries. - `success` (boolean): `true` when the history was returned. - `data` (array of object): The bookings of this page, newest first. eSIM topups are listed next to eSIM orders. - `product` (string): The product of the booking. One of `flights`, `hotels`, `esims`, `transfers`. - `id` (string (uuid)): Internal id of the booking (UUID). Stable and unique: store it as your key. - `bookingId` (string, deprecated): Legacy name: use `booking_id`. The public reference of the booking: the airline record locator of a flight (not unique across suppliers), the hotel booking id, `FX-` followed by a number for an eSIM, or the transfer reference. The older name of `booking_id`: same value, use `booking_id`. - `booking_id` (string): The public reference of the booking: the airline record locator of a flight (not unique across suppliers), the hotel booking id, `FX-` followed by a number for an eSIM, or the transfer reference. The snake_case twin of `bookingId`, with the same value: use this name. - `status` (string): State of the booking. The values depend on the product: for example `confirmed`, `awaiting_payment` (a held flight that is not paid), `cancelled`, `failed`, `refunded`, `partial_refund`. - `environment` (string): The environment of the key that made the call: `sandbox` for fxp_test_ keys, `live` for fxp_live_ keys. Present in every JSON body. One of `sandbox`, `live`. - `agencyId` (string (uuid), deprecated): Legacy name: use `agency_id`. The id of your agency. The older name of `agency_id`: same value, use `agency_id`. - `agency_id` (string (uuid)): The id of your agency. The snake_case twin of `agencyId`, with the same value: use this name. - `agentId` (string, nullable, deprecated): Legacy name: use `agent_id`. The user of your agency who created the booking, or null when it was created through an API key without a user. The older name of `agent_id`: same value, use `agent_id`. - `agent_id` (string, nullable): The user of your agency who created the booking, or null when it was created through an API key without a user. The snake_case twin of `agentId`, with the same value: use this name. - `currency` (string): Currency of the amounts: the settlement currency of your agency. - `totalPrice` (number, deprecated): Legacy name: use `total_price`. What the traveler pays, in your agency currency. It includes your commission. The older name of `total_price`: same value, use `total_price`. - `total_price` (number): What the traveler pays, in your agency currency. It includes your commission. The snake_case twin of `totalPrice`, with the same value: use this name. - `netPrice` (number, deprecated): Legacy name: use `b2b_price`. The amount debited from your agency balance: `totalPrice` minus `agencyCommission`. The older name of `b2b_price`: same value, use `b2b_price`. - `b2b_price` (number): The amount debited from your agency balance: `totalPrice` minus `agencyCommission`. The snake_case twin of `netPrice`, with the same value: use this name. - `agencyCommission` (number, deprecated): Legacy name: use `agency_commission`. Your commission as an amount, in your agency currency. `0` when there is none. The older name of `agency_commission`: same value, use `agency_commission`. - `agency_commission` (number): Your commission as an amount, in your agency currency. `0` when there is none. The snake_case twin of `agencyCommission`, with the same value: use this name. - `providerName` (string, nullable, deprecated): Legacy name: use `provider_name`. Name of the supplier that fulfilled the booking. The older name of `provider_name`: same value, use `provider_name`. - `provider_name` (string, nullable): Name of the supplier that fulfilled the booking. The snake_case twin of `providerName`, with the same value: use this name. - `supplierId` (string, nullable, deprecated): Legacy name: use `supplier_id`. Id of the supplier that fulfilled the booking, as stored on the booking. It can differ from the id the supplier list uses: `ratehawk` and `airalo` here are `worldota_1` and `airalo_1` there. The older name of `supplier_id`: same value, use `supplier_id`. - `supplier_id` (string, nullable): Id of the supplier that fulfilled the booking, as stored on the booking. It can differ from the id the supplier list uses: `ratehawk` and `airalo` here are `worldota_1` and `airalo_1` there. The snake_case twin of `supplierId`, with the same value: use this name. - `createdAt` (string, deprecated): Legacy name: use `created_at`. When the booking was created: ISO 8601, UTC. The older name of `created_at`: same value, use `created_at`. - `created_at` (string): When the booking was created: ISO 8601, UTC. The snake_case twin of `createdAt`, with the same value: use this name. - `updatedAt` (string, deprecated): Legacy name: use `updated_at`. When the booking last changed: ISO 8601, UTC. The older name of `updated_at`: same value, use `updated_at`. - `updated_at` (string): When the booking last changed: ISO 8601, UTC. The snake_case twin of `updatedAt`, with the same value: use this name. - `departureAirport` (string): Flights only. IATA code of the first departure airport. - `arrivalAirport` (string): Flights only. IATA code of the final arrival airport. - `departureDate` (string): Flights only. Local departure date and time of the first segment, without a zone. - `arrivalDate` (string): Flights and transfers. Local arrival date and time, without a zone for flights. - `ticketNumber` (string, nullable): Flights only. The ticket number once issued, or null. - `requireAcd` (boolean, nullable, deprecated): Legacy name: use `require_acd`. Flights only. Whether the booking needs ACD documents. The older name of `require_acd`: same value, use `require_acd`. - `require_acd` (boolean, nullable): Flights only. Whether the booking needs ACD documents. The snake_case twin of `requireAcd`, with the same value: use this name. - `voucherUrl` (string, nullable): Flights and hotels: the confirmation PDF with prices (same as `voucherUrlWithPrice`), null while it is generated. Transfers: the supplier voucher, null until a driver is assigned. - `voucherUrlWithPrice` (string, nullable): Flights and hotels. The confirmation PDF with prices. - `voucherUrlNoPrice` (string, nullable): Flights and hotels. The confirmation PDF without prices, to give to the traveler. - `hotelId` (string): Hotels only. The id of the hotel. - `hotelName` (string, nullable): Hotels only. The name of the hotel, or null when the supplier did not give one (a failed booking, for example). - `checkinDate` (string): Hotels only. Check-in date: `YYYY-MM-DD`. - `checkoutDate` (string): Hotels only. Check-out date: `YYYY-MM-DD`. - `bookingMode` (string, nullable): Hotels only. How the booking was made, for example `standard`. - `orderId` (string, deprecated): Legacy name: use `order_id`. eSIMs only. The supplier's order code. The older name of `order_id`: same value, use `order_id`. - `order_id` (string): eSIMs only. The supplier's order code. The snake_case twin of `orderId`, with the same value: use this name. - `type` (string): eSIMs only. `esim` for an order, `topup` for a topup. One of `esim`, `topup`. - `packageName` (string, deprecated): Legacy name: use `package_name`. eSIMs only. Name of the package. The older name of `package_name`: same value, use `package_name`. - `package_name` (string): eSIMs only. Name of the package. The snake_case twin of `packageName`, with the same value: use this name. - `iccid` (string): eSIMs only. The ICCID of the eSIM. - `customerEmail` (string, deprecated): Legacy name: use `customer_email`. eSIMs only. The traveler's email. The older name of `customer_email`: same value, use `customer_email`. - `customer_email` (string): eSIMs only. The traveler's email. The snake_case twin of `customerEmail`, with the same value: use this name. - `customer_first_name` (string): eSIMs only. The traveler's first name. - `customer_last_name` (string): eSIMs only. The traveler's last name. - `customer_phone` (string): eSIMs only. The traveler's phone number. - `flightNumber` (string, nullable): Transfers only. The flight number the transfer was booked for. - `receiptUrl` (string, nullable): Transfers only. FX-Port's receipt PDF, once the booking is confirmed. - `pagination` (object): Where this page sits in the list. - `page` (integer): The page returned. - `limit` (integer): The page size used. - `total` (integer): Number of matching entries. Only the newest ones can be paged to (see the endpoint): follow `has_more`, not `total`. - `total_pages` (integer): Number of pages: `total` divided by `limit`, rounded up. Absent when the count is not available. - `hasMore` (boolean, deprecated): Legacy name: use `has_more`. `true` when another page can be served. The older name of `has_more`: same value, use `has_more`. - `has_more` (boolean): `true` when another page can be served. The snake_case twin of `hasMore`, with the same value: use this name. - `meta` (object): Facts about the answer. - `agencyId` (string (uuid), deprecated): Legacy name: use `agency_id`. The id of your agency, resolved from the key. The older name of `agency_id`: same value, use `agency_id`. - `agency_id` (string (uuid)): The id of your agency, resolved from the key. The snake_case twin of `agencyId`, with the same value: use this name. - `environment` (string): The environment of the key that made the call: `sandbox` for fxp_test_ keys, `live` for fxp_live_ keys. Present in every JSON body. One of `sandbox`, `live`. - `product` (string): The `product` filter that was applied, `all` by default. ```json { "environment": "sandbox", "success": true, "data": [ { "product": "esims", "id": "bd6ff7d7-392f-4d56-8dea-4f0f3dff0af9", "bookingId": "FX-1793546625391", "booking_id": "FX-1793546625391", "status": "confirmed", "environment": "sandbox", "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "agentId": null, "agent_id": null, "currency": "DZD", "totalPrice": 468.84, "total_price": 468.84, "netPrice": 418.6, "b2b_price": 418.6, "agencyCommission": 50.24, "agency_commission": 50.24, "providerName": "Airalo", "provider_name": "Airalo", "supplierId": "airalo", "supplier_id": "airalo", "createdAt": "2026-11-01T15:23:45.424526+00:00", "created_at": "2026-11-01T15:23:45.424526+00:00", "updatedAt": "2026-11-01T15:23:45.424526+00:00", "updated_at": "2026-11-01T15:23:45.424526+00:00", "orderId": "20261101-106853", "order_id": "20261101-106853", "type": "topup", "packageName": "1 GB - 7 days", "package_name": "1 GB - 7 days", "iccid": "8900000540463077957", "customerEmail": "traveler@example.com", "customer_email": "traveler@example.com", "customer_first_name": "John", "customer_last_name": "Smith", "customer_phone": "+15555550123" }, { "product": "esims", "id": "639417b4-b103-4ece-bd5d-850315322278", "bookingId": "FX-1793546602916", "booking_id": "FX-1793546602916", "status": "confirmed", "environment": "sandbox", "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "agentId": null, "agent_id": null, "currency": "DZD", "totalPrice": 468.84, "total_price": 468.84, "netPrice": 418.6, "b2b_price": 418.6, "agencyCommission": 50.24, "agency_commission": 50.24, "providerName": "Airalo", "provider_name": "Airalo", "supplierId": "airalo", "supplier_id": "airalo", "createdAt": "2026-11-01T15:23:22.961228+00:00", "created_at": "2026-11-01T15:23:22.961228+00:00", "updatedAt": "2026-11-01T15:23:22.961228+00:00", "updated_at": "2026-11-01T15:23:22.961228+00:00", "orderId": "20261101-106852", "order_id": "20261101-106852", "type": "esim", "packageName": "1 GB - 7 days • France", "package_name": "1 GB - 7 days • France", "iccid": "8900000540463077957", "customerEmail": "traveler@example.com", "customer_email": "traveler@example.com", "customer_first_name": "John", "customer_last_name": "Smith", "customer_phone": "+15555550123" } ], "pagination": { "page": 1, "limit": 2, "total": 80, "total_pages": 40, "hasMore": true, "has_more": true }, "meta": { "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "environment": "sandbox", "product": "esims" } } ``` ## Errors | Status | Code | Example message | | --- | --- | --- | | 400 | `invalid_product` | product must be one of all, esims, flights, hotels, transfers. | | 400 | `invalid_date` | Date parameters must be ISO-8601 values, for example 2026-05-08 or 2026-05-08T10:30:00Z. | | 400 | `invalid_date_range` | date_from must not be after date_to. | | 400 | `agency_id_not_allowed` | External API keys resolve agency_id automatically; do not send agency_id as a query parameter. | | 422 | `validation_error` | Input should be less than or equal to 100 | | 503 | `service_overloaded` | The service is temporarily overloaded; retry after the time given in the Retry-After header. | See [Errors](https://fx-port.com/docs/errors.md) for every code and how to react. ## Related guides - [Booking history](https://fx-port.com/docs/account/history.md)