Skip to content
FX-Port/Docs
GuidesAPI referenceChangelog
Get API keys
  • Overview
  • Error object

Balances

  • BalancesGET
  • Balance historyGET

Bookings

  • Booking historyGET
  • Get a bookingGET

Suppliers

  • SuppliersGET

Objects

  • Account booking

Account · Bookings

List booking history

List the bookings of your agency across flights, hotels, eSIMs and transfers, newest first, as short summaries.

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.

curl 'https://api.fx-port.com/api/v1/history?product=esims&limit=2' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
Response200
{
  "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": "[email protected]",
      "customer_email": "[email protected]",
      "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": "[email protected]",
      "customer_email": "[email protected]",
      "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"
  }
}
Response200
{
  "environment": "sandbox",
  "success": true,
  "data": [
    {
      "product": "flights",
      "id": "8723790a-0417-46bb-8247-07254b214a4c",
      "bookingId": "Y7INFJ",
      "booking_id": "Y7INFJ",
      "status": "awaiting_payment",
      "environment": "sandbox",
      "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
      "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
      "agentId": null,
      "agent_id": null,
      "currency": "DZD",
      "totalPrice": 32593.93,
      "total_price": 32593.93,
      "netPrice": 32561.36,
      "b2b_price": 32561.36,
      "agencyCommission": 32.57,
      "agency_commission": 32.57,
      "providerName": "Amadeus Algeria",
      "provider_name": "Amadeus Algeria",
      "supplierId": "amadeus_aqc_dz_1",
      "supplier_id": "amadeus_aqc_dz_1",
      "createdAt": "2026-11-01T14:31:20.248661+00:00",
      "created_at": "2026-11-01T14:31:20.248661+00:00",
      "updatedAt": "2026-11-01T14:31:22.611902+00:00",
      "updated_at": "2026-11-01T14:31:22.611902+00:00",
      "departureAirport": "ALG",
      "arrivalAirport": "CDG",
      "departureDate": "2026-12-15T07:15:00",
      "arrivalDate": "2026-12-15T09:45:00",
      "ticketNumber": null,
      "requireAcd": false,
      "require_acd": false,
      "voucherUrl": "https://files.example.com/flight-bookings/Y7INFJ-JOHN-SMITH.pdf",
      "voucherUrlWithPrice": "https://files.example.com/flight-bookings/Y7INFJ-JOHN-SMITH.pdf",
      "voucherUrlNoPrice": "https://files.example.com/flight-bookings/Y7INFJ-JOHN-SMITH-no-price.pdf"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 2,
    "total_pages": 2,
    "hasMore": true,
    "has_more": true
  },
  "meta": {
    "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "environment": "sandbox",
    "product": "flights"
  }
}
Response200
{
  "environment": "sandbox",
  "success": true,
  "data": [
    {
      "product": "hotels",
      "id": "34a08cf3-dff6-45c6-bdae-882061aa78f5",
      "bookingId": "HMVXX4ZQ3",
      "booking_id": "HMVXX4ZQ3",
      "status": "refunded",
      "environment": "sandbox",
      "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
      "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
      "agentId": null,
      "agent_id": null,
      "currency": "DZD",
      "totalPrice": 1484.97,
      "total_price": 1484.97,
      "netPrice": 1482,
      "b2b_price": 1482,
      "agencyCommission": 2.97,
      "agency_commission": 2.97,
      "providerName": "ETG - RateHawk",
      "provider_name": "ETG - RateHawk",
      "supplierId": "ratehawk",
      "supplier_id": "ratehawk",
      "createdAt": "2026-11-01T14:22:00.924125+00:00",
      "created_at": "2026-11-01T14:22:00.924125+00:00",
      "updatedAt": "2026-11-01T14:22:32.992144+00:00",
      "updated_at": "2026-11-01T14:22:32.992144+00:00",
      "hotelId": "test_hotel_do_not_book",
      "hotelName": "Test Hotel (Do Not Book) test",
      "checkinDate": "2026-12-01",
      "checkoutDate": "2026-12-04",
      "bookingMode": "standard",
      "voucherUrl": "https://files.example.com/hotel-bookings/HMVXX4ZQ3-Jane-Smith.pdf",
      "voucherUrlWithPrice": "https://files.example.com/hotel-bookings/HMVXX4ZQ3-Jane-Smith.pdf",
      "voucherUrlNoPrice": "https://files.example.com/hotel-bookings/HMVXX4ZQ3-Jane-Smith-no-price.pdf"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 86,
    "total_pages": 86,
    "hasMore": true,
    "has_more": true
  },
  "meta": {
    "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "environment": "sandbox",
    "product": "hotels"
  }
}
Response200
{
  "environment": "sandbox",
  "success": true,
  "data": [
    {
      "product": "transfers",
      "id": "4745c761-0737-421a-aaab-c90f9c0aca8f",
      "bookingId": "VIA-1782555657-QCF",
      "booking_id": "VIA-1782555657-QCF",
      "status": "refunded",
      "environment": "sandbox",
      "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
      "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
      "agentId": "5d6e7f80-91a2-4b3c-8d4e-5f6071829304",
      "agent_id": "5d6e7f80-91a2-4b3c-8d4e-5f6071829304",
      "currency": "DZD",
      "totalPrice": 15124.38,
      "total_price": 15124.38,
      "netPrice": 15002.38,
      "b2b_price": 15002.38,
      "agencyCommission": 122,
      "agency_commission": 122,
      "providerName": "AirportTransfer.com",
      "provider_name": "AirportTransfer.com",
      "supplierId": null,
      "supplier_id": null,
      "createdAt": "2026-06-27T10:20:59.188372+00:00",
      "created_at": "2026-06-27T10:20:59.188372+00:00",
      "updatedAt": "2026-06-27T10:29:28.684+00:00",
      "updated_at": "2026-06-27T10:29:28.684+00:00",
      "arrivalDate": "2026-08-14T16:00:00+00:00",
      "flightNumber": "593",
      "voucherUrl": null,
      "receiptUrl": "https://files.example.com/transfer-bookings/VIA-1782555657-QCF.pdf"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 2,
    "total_pages": 2,
    "hasMore": true,
    "has_more": true
  },
  "meta": {
    "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "environment": "sandbox",
    "product": "transfers"
  }
}

Request

Query parameters

productstring

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.

statusstring

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_fromstring

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_tostring

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.

fromstringdeprecated

Legacy name, still accepted. Use date_from instead.

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_datestringdeprecated

Legacy name, still accepted. Use date_from instead.

Previous name of date_from. It still works, with the same spellings, and the response carries a deprecated_field warning.

At most 40 characters.

tostringdeprecated

Legacy name, still accepted. Use date_to instead.

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_datestringdeprecated

Legacy name, still accepted. Use date_to instead.

Previous name of date_to. It still works, with the same spellings, and the response carries a deprecated_field warning.

At most 40 characters.

pageinteger

The page, starting at 1 (at most 10000). An empty value means not sent.

Between 1 and 10000. Default 1.

limitinteger

Entries per page, from 1 to 100. An empty value means not sent.

Between 1 and 100. Default 20.

Response

200A page of booking summaries.

successboolean

true when the history was returned.

dataarray of object

The bookings of this page, newest first. eSIM topups are listed next to eSIM orders.

ShowHide 53 attributes
productstring

The product of the booking.

One of flights, hotels, esims, transfers.

idstring (uuid)

Internal id of the booking (UUID). Stable and unique: store it as your key.

bookingIdstringdeprecated

Legacy name, still accepted. Use booking_id instead.

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_idstring

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.

statusstring

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.

environmentstring

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.

agencyIdstring (uuid)deprecated

Legacy name, still accepted. Use agency_id instead.

The id of your agency. The older name of agency_id: same value, use agency_id.

agency_idstring (uuid)

The id of your agency. The snake_case twin of agencyId, with the same value: use this name.

agentIdstringnullabledeprecated

Legacy name, still accepted. Use agent_id instead.

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_idstringnullable

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.

currencystring

Currency of the amounts: the settlement currency of your agency.

totalPricenumberdeprecated

Legacy name, still accepted. Use total_price instead.

What the traveler pays, in your agency currency. It includes your commission. The older name of total_price: same value, use total_price.

total_pricenumber

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.

netPricenumberdeprecated

Legacy name, still accepted. Use b2b_price instead.

The amount debited from your agency balance: totalPrice minus agencyCommission. The older name of b2b_price: same value, use b2b_price.

b2b_pricenumber

The amount debited from your agency balance: totalPrice minus agencyCommission. The snake_case twin of netPrice, with the same value: use this name.

agencyCommissionnumberdeprecated

Legacy name, still accepted. Use agency_commission instead.

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_commissionnumber

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.

providerNamestringnullabledeprecated

Legacy name, still accepted. Use provider_name instead.

Name of the supplier that fulfilled the booking. The older name of provider_name: same value, use provider_name.

provider_namestringnullable

Name of the supplier that fulfilled the booking. The snake_case twin of providerName, with the same value: use this name.

supplierIdstringnullabledeprecated

Legacy name, still accepted. Use supplier_id instead.

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_idstringnullable

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.

createdAtstringdeprecated

Legacy name, still accepted. Use created_at instead.

When the booking was created: ISO 8601, UTC. The older name of created_at: same value, use created_at.

created_atstring

When the booking was created: ISO 8601, UTC. The snake_case twin of createdAt, with the same value: use this name.

updatedAtstringdeprecated

Legacy name, still accepted. Use updated_at instead.

When the booking last changed: ISO 8601, UTC. The older name of updated_at: same value, use updated_at.

updated_atstring

When the booking last changed: ISO 8601, UTC. The snake_case twin of updatedAt, with the same value: use this name.

departureAirportstring

Flights only. IATA code of the first departure airport.

arrivalAirportstring

Flights only. IATA code of the final arrival airport.

departureDatestring

Flights only. Local departure date and time of the first segment, without a zone.

arrivalDatestring

Flights and transfers. Local arrival date and time, without a zone for flights.

ticketNumberstringnullable

Flights only. The ticket number once issued, or null.

requireAcdbooleannullabledeprecated

Legacy name, still accepted. Use require_acd instead.

Flights only. Whether the booking needs ACD documents. The older name of require_acd: same value, use require_acd.

require_acdbooleannullable

Flights only. Whether the booking needs ACD documents. The snake_case twin of requireAcd, with the same value: use this name.

voucherUrlstringnullable

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.

voucherUrlWithPricestringnullable

Flights and hotels. The confirmation PDF with prices.

voucherUrlNoPricestringnullable

Flights and hotels. The confirmation PDF without prices, to give to the traveler.

hotelIdstring

Hotels only. The id of the hotel.

hotelNamestringnullable

Hotels only. The name of the hotel, or null when the supplier did not give one (a failed booking, for example).

checkinDatestring

Hotels only. Check-in date: YYYY-MM-DD.

checkoutDatestring

Hotels only. Check-out date: YYYY-MM-DD.

bookingModestringnullable

Hotels only. How the booking was made, for example standard.

orderIdstringdeprecated

Legacy name, still accepted. Use order_id instead.

eSIMs only. The supplier's order code. The older name of order_id: same value, use order_id.

order_idstring

eSIMs only. The supplier's order code. The snake_case twin of orderId, with the same value: use this name.

typestring

eSIMs only. esim for an order, topup for a topup.

One of esim, topup.

packageNamestringdeprecated

Legacy name, still accepted. Use package_name instead.

eSIMs only. Name of the package. The older name of package_name: same value, use package_name.

package_namestring

eSIMs only. Name of the package. The snake_case twin of packageName, with the same value: use this name.

iccidstring

eSIMs only. The ICCID of the eSIM.

customerEmailstringdeprecated

Legacy name, still accepted. Use customer_email instead.

eSIMs only. The traveler's email. The older name of customer_email: same value, use customer_email.

customer_emailstring

eSIMs only. The traveler's email. The snake_case twin of customerEmail, with the same value: use this name.

customer_first_namestring

eSIMs only. The traveler's first name.

customer_last_namestring

eSIMs only. The traveler's last name.

customer_phonestring

eSIMs only. The traveler's phone number.

flightNumberstringnullable

Transfers only. The flight number the transfer was booked for.

receiptUrlstringnullable

Transfers only. FX-Port's receipt PDF, once the booking is confirmed.

paginationobject

Where this page sits in the list.

ShowHide 6 attributes
pageinteger

The page returned.

limitinteger

The page size used.

totalinteger

Number of matching entries. Only the newest ones can be paged to (see the endpoint): follow has_more, not total.

total_pagesinteger

Number of pages: total divided by limit, rounded up. Absent when the count is not available.

hasMorebooleandeprecated

Legacy name, still accepted. Use has_more instead.

true when another page can be served. The older name of has_more: same value, use has_more.

has_moreboolean

true when another page can be served. The snake_case twin of hasMore, with the same value: use this name.

metaobject

Facts about the answer.

ShowHide 4 attributes
agencyIdstring (uuid)deprecated

Legacy name, still accepted. Use agency_id instead.

The id of your agency, resolved from the key. The older name of agency_id: same value, use agency_id.

agency_idstring (uuid)

The id of your agency, resolved from the key. The snake_case twin of agencyId, with the same value: use this name.

environmentstring

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.

productstring

The product filter that was applied, all by default.

Errors

StatusCodeExample message
400invalid_productproduct must be one of all, esims, flights, hotels, transfers.
400invalid_dateDate parameters must be ISO-8601 values, for example 2026-05-08 or 2026-05-08T10:30:00Z.
400invalid_date_rangedate_from must not be after date_to.
400agency_id_not_allowedExternal API keys resolve agency_id automatically; do not send agency_id as a query parameter.
422validation_errorInput should be less than or equal to 100
503service_overloadedThe service is temporarily overloaded; retry after the time given in the Retry-After header.

The shape of the error body depends on the endpoint. See Errors for every shape and code.

Related guides

  • Booking history
PreviousGet the history of a balanceNext Get a booking

© 2026 FX-Port

TermsPrivacy[email protected]