Booking detail
A single booking by its public reference, with the pricing breakdown and the traveler pricing.
GET/api/v1/bookings/{booking_id}
GET /
Permission: Read
Returns one booking of your agency, whatever its product: the summary of the history, the stored record, and, for flights and hotels, the price breakdown and the balance operations; for flights also the price per traveler.
The reference you can send
booking_id is the internal id of the booking (a UUID) or the public reference of its product. The reference is
looked up in these fields, in this order, and the first booking found is returned:
| Product | Fields tried |
|---|---|
flights | booking_id (the airline record locator, the PNR), the supplier's order id, then id |
hotels | booking_id, then id |
esims | booking_id (FX- followed by a number), the supplier's order code (order_id), the ICCID (18 to 22 digits, or a PENDING-... placeholder), then id |
transfers | booking_id, then id |
Without product, the products are tried in the order flights, hotels, eSIMs, transfers. The reference is at most 100
characters: letters, digits and ._:=+~- (400 invalid_booking_id otherwise).
An ICCID returns the original order, never a later topup. An eSIM that was topped up has several bookings with the same
ICCID; the lookup by ICCID answers the oldest order of type esim. Look a topup up by its booking_id or its id.
Query parameters
| Parameter | Default | Description |
|---|---|---|
product | all | Look in one product only: flights, hotels, esims or transfers (case does not matter; the singular names are read as the plural). It is faster, and it avoids a match in another product. A reference that belongs to another product than the one you ask for is 404 booking_not_found |
Never send agency_id: an API key that does is refused with 400 agency_id_not_allowed.
Request examples
# Recommended: the internal id (a UUID), which is unambiguous
curl --get \
--url https://api.fx-port.com/api/v1/bookings/711371c3-00aa-4be2-b790-9f0ca2ccfdb7 \
--header 'Authorization: Bearer fxp_test_YOUR_KEY' \
--data-urlencode 'product=flights'
# An eSIM order by its public reference
curl --get \
--url https://api.fx-port.com/api/v1/bookings/FX-1793546602916 \
--header 'Authorization: Bearer fxp_test_YOUR_KEY' \
--data-urlencode 'product=esims'const id = "711371c3-00aa-4be2-b790-9f0ca2ccfdb7";
const response = await fetch(`https://api.fx-port.com/api/v1/bookings/${id}?product=flights`, {
headers: { Authorization: "Bearer fxp_test_YOUR_KEY" },
});
if (response.status === 404) {
// booking_not_found: not in this environment, or not in this product
}
const { data: booking } = await response.json();import requests
response = requests.get(
"https://api.fx-port.com/api/v1/bookings/FX-1793546602916",
params={"product": "esims"},
headers={"Authorization": "Bearer fxp_test_YOUR_KEY"},
timeout=30,
)
booking = response.json()["data"]Response examples
An eSIM order (a sandbox answer). The summary keys come with their snake_case twins:
{
"environment": "sandbox",
"success": true,
"data": {
"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",
"record": {
"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": "[email protected]",
"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"
}
},
"meta": {
"agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"environment": "sandbox"
}
}A confirmed flight, shortened: the summary keeps only some of its keys (the history lists them
all), the snake_case twins are left out, and record leaves out its keys without a value:
{
"environment": "sandbox",
"success": true,
"data": {
"product": "flights",
"id": "711371c3-00aa-4be2-b790-9f0ca2ccfdb7",
"bookingId": "Y7PAEU",
"status": "confirmed",
"environment": "sandbox",
"currency": "DZD",
"totalPrice": 4930.37,
"netPrice": 4925.44,
"agencyCommission": 4.93,
"providerName": "Amadeus Algeria",
"supplierId": "amadeus_aqc_dz_1",
"ticketNumber": "124-2446977397",
"record": {
"id": "711371c3-00aa-4be2-b790-9f0ca2ccfdb7",
"booking_id": "Y7PAEU",
"status": "confirmed",
"currency": "DZD",
"total_price": 4930.37,
"agency_commission": 4.93,
"departure_airport": "ALG",
"arrival_airport": "ORN",
"departure_date": "2026-12-22T19:45:00",
"arrival_date": "2026-12-22T20:45:00",
"ticket_number": "124-2446977397",
"require_acd": false,
"bucket_link": "https://files.example.com/flight-bookings/Y7PAEU-JAMES-SMITH-confirmed.pdf",
"bucket_link_no_price": "https://files.example.com/flight-bookings/Y7PAEU-JAMES-SMITH-confirmed-no-price.pdf",
"paid_at": "2026-11-01T15:26:14.842190+00:00",
"created_at": "2026-11-01T15:26:14.871035+00:00",
"updated_at": "2026-11-01T15:26:23.505356+00:00",
"environment": "sandbox"
},
"pricing": [
{
"supplier_currency": "DZD",
"agency_currency": "DZD",
"base_price": 3160.0,
"taxes_and_fees": 1765.44,
"agency_commission": 4.93,
"final_price": 4930.37,
"b2b_price": 4925.44,
"created_at": "2026-11-01T15:26:22.176516+00:00",
"environment": "sandbox"
}
],
"travelerPricing": [
{
"traveler_id": "1",
"traveler_type": "ADULT",
"fare_option": "STANDARD",
"supplier_currency": "DZD",
"agency_currency": "DZD",
"base": 3160.0,
"total": 4930.37,
"b2b_price": 4925.44,
"created_at": "2026-11-01T15:26:15.133066+00:00",
"environment": "sandbox"
}
],
"balanceOperations": []
},
"meta": { "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "environment": "sandbox" }
}A refunded hotel booking, shortened the same way:
{
"environment": "sandbox",
"success": true,
"data": {
"product": "hotels",
"id": "34a08cf3-dff6-45c6-bdae-882061aa78f5",
"bookingId": "HMVXX4ZQ3",
"status": "refunded",
"environment": "sandbox",
"currency": "DZD",
"totalPrice": 1484.97,
"netPrice": 1482.0,
"agencyCommission": 2.97,
"providerName": "ETG - RateHawk",
"supplierId": "ratehawk",
"hotelId": "test_hotel_do_not_book",
"checkinDate": "2026-12-01",
"checkoutDate": "2026-12-04",
"record": {
"id": "34a08cf3-dff6-45c6-bdae-882061aa78f5",
"booking_id": "HMVXX4ZQ3",
"status": "refunded",
"currency": "DZD",
"total_price": 1484.97,
"agency_commission": 2.97,
"hotel_id": "test_hotel_do_not_book",
"hotel_name": "Test Hotel (Do Not Book) test",
"checkin_date": "2026-12-01",
"checkout_date": "2026-12-04",
"booking_mode": "standard",
"free_cancellation_deadline_at": null,
"supplier_id": "ratehawk",
"refund_amount": 1482.0,
"refund_currency": "DZD",
"environment": "sandbox"
},
"pricing": [
{
"id": "72db7216-177e-4c5b-bde6-74c5ca3c8db2",
"created_at": "2026-11-01T14:22:05.162117+00:00",
"agency_currency": "DZD",
"total_price": 1484.97,
"agency_commission": 2.97,
"environment": "sandbox",
"b2b_price": 1482.0
}
],
"balanceOperations": []
},
"meta": { "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "environment": "sandbox" }
}A transfer has the summary and the record only. The balance operations of a flight or a hotel are empty in the
sandbox.
Field reference
Summary. The keys before record are the ones of the history, with the same
snake_case twins.
record is the stored booking in snake_case. A key that does not apply to the product is absent.
| Product | Keys of record |
|---|---|
| All | id, booking_id, status, currency, total_price, agency_commission, created_at, updated_at, environment |
| Flights | departure_airport, arrival_airport, departure_date, arrival_date, return_departure_date, return_arrival_date, included_checked_bags, ticket_number (the e-ticket number once issued), require_acd, bucket_link (the confirmation PDF with prices), bucket_link_no_price, refund_amount, refund_currency, refund_method, paid_at, voided_at |
| Hotels | hotel_id, hotel_name, checkin_date, checkout_date, booking_mode, bucket_link, bucket_link_no_price, refund_amount, refund_currency, free_cancellation_deadline_at, paid_at, supplier_id |
| eSIMs | order_id, type, package_name, iccid, customer_email, customer_first_name, customer_last_name, customer_phone, provider_name, supplier_id |
| Transfers | arrival_date, flight_number, provider_name, bucket_link (FX-Port's receipt), voucher_link (the supplier voucher), refunded_amount, refunded_currency |
pricing[] (flights and hotels)
| Field | Description |
|---|---|
agency_currency | Your agency currency |
base_price, taxes_and_fees | Flights. The fare before taxes, and the taxes and fees without your commission |
final_price | Flights. What the traveler pays: base_price + taxes_and_fees + agency_commission |
total_price | Hotels. What the traveler pays |
agency_commission | Your commission as an amount |
b2b_price | The amount debited from your agency balance: the total minus agency_commission |
supplier_currency | Flights. The currency the supplier prices in |
travelerPricing[] (flights; twin traveler_pricing): one row per traveler with traveler_id, traveler_type, fare_option,
base, total and b2b_price (the amount debited for this traveler).
balanceOperations[] (flights and hotels; twin balance_operations): the balance operations of the booking with
id, type (debit, credit or refund), amount, currency, description and createdAt (created_at). They are the same
operations as the *_balance_operations entries of the balance history.
Errors
| HTTP | code | Cause |
|---|---|---|
400 | invalid_booking_id | The reference is longer than 100 characters or has characters other than letters, digits and ._:=+~- |
400 | invalid_product | product is not one of the allowed values |
400 | agency_id_not_allowed | An API key sent agency_id |
401 | authentication_required, invalid_api_key | Missing or invalid API key |
404 | booking_not_found | No booking of your agency in this environment has this reference, or it belongs to another product than product |
429 | rate_limit_exceeded | Over 6,000 requests per minute for this key |
503 | service_overloaded | The service is shedding load for a moment (its database pool is full). Nothing was read: retry after the seconds in Retry-After (2 to 5) |