Skip to content
FX-Port/Docs
GuidesAPI referenceChangelog
Get API keys
  • Introduction
  • Quickstart
  • Security
  • Authentication
  • Environments and Postman
  • Sandbox
  • Conventions and naming
  • Legacy names and twins
  • Errors
  • Rate limits and fair use
  • Streaming search results

Account and suppliers

  • Suppliers
  • Overview
  • List balances
  • Balance history
  • Booking history
  • Booking detail
  • Use these docs with AI

Account · Account and suppliers

Booking detail

A single booking by its public reference, with the pricing breakdown and the traveler pricing.

GET/api/v1/bookings/{booking_id}

GET /api/v1/bookings/{booking_id}

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:

ProductFields tried
flightsbooking_id (the airline record locator, the PNR), the supplier's order id, then id
hotelsbooking_id, then id
esimsbooking_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
transfersbooking_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).

Prefer the internal id (UUID). A PNR or a booking reference is not globally unique: the same record locator can exist at two airlines or suppliers, so a lookup by PNR can match another booking than the one you mean. The internal id is in every booking payload, unique and stable: store it, and treat the PNR as a display reference.

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

ParameterDefaultDescription
productallLook 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.

ProductKeys of record
Allid, booking_id, status, currency, total_price, agency_commission, created_at, updated_at, environment
Flightsdeparture_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
Hotelshotel_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
eSIMsorder_id, type, package_name, iccid, customer_email, customer_first_name, customer_last_name, customer_phone, provider_name, supplier_id
Transfersarrival_date, flight_number, provider_name, bucket_link (FX-Port's receipt), voucher_link (the supplier voucher), refunded_amount, refunded_currency

pricing[] (flights and hotels)

FieldDescription
agency_currencyYour agency currency
base_price, taxes_and_feesFlights. The fare before taxes, and the taxes and fees without your commission
final_priceFlights. What the traveler pays: base_price + taxes_and_fees + agency_commission
total_priceHotels. What the traveler pays
agency_commissionYour commission as an amount
b2b_priceThe amount debited from your agency balance: the total minus agency_commission
supplier_currencyFlights. 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

HTTPcodeCause
400invalid_booking_idThe reference is longer than 100 characters or has characters other than letters, digits and ._:=+~-
400invalid_productproduct is not one of the allowed values
400agency_id_not_allowedAn API key sent agency_id
401authentication_required, invalid_api_keyMissing or invalid API key
404booking_not_foundNo booking of your agency in this environment has this reference, or it belongs to another product than product
429rate_limit_exceededOver 6,000 requests per minute for this key
503service_overloadedThe 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)
PreviousBooking historyNext Use these docs with AI

On this page

  • The reference you can send
  • Query parameters
  • Request examples
  • Response examples
  • Field reference
  • Errors

© 2026 FX-Port

TermsPrivacy[email protected]