Flight booking flows
Step-by-step flight booking flows — instant issue, hold-then-pay, and how cancellation of a held PNR works.
Every flight booking follows one of two flows. Both start with a search and a mandatory pricing step.
Instant issue (most common)
Tickets are issued immediately after booking.
Search for flights
POST /api/v1/get_flights — returns offers from one or all suppliers. Each supplier entry has
a searchId — save it for the next steps.
Price the offer (required)
POST /api/v1/flights/price_flight — confirms the current fare and caches the priced offer.
This step is mandatory — book_flight reads the priced offer from cache. Booking without
pricing first will fail.
Book and issue tickets
POST /api/v1/flights/book_flight with "booking_type": "issue" — tickets are issued
immediately. The response contains booking.reference (the supplier order ID) and booking.pnr.
Retrieve booking + PDF
POST /api/v1/flights/get_booking — returns the full booking record. Once the PDF is generated
(typically 10–30 seconds), booking.bucket_link contains the download URL.
GET_FLIGHTS → PRICE_FLIGHT → BOOK_FLIGHT (issue) → GET_BOOKINGHold then pay (suppliers supporting holds only)
Reserve a seat without paying, then pay later. Use this flow only when the selected search and
priced offer return supportHold: true. Never infer hold support from a supplier name; capability
can vary by supplier, airline, fare, and offer.
Search and price — same as instant issue (steps 1 and 2 above).
Create a hold reservation
POST /api/v1/flights/book_flight with "booking_type": "hold" — a reservation is created
without ticket issuance or a balance charge. The immediate supplier response may use
booking.status: "pending"; stored booking and quote responses use "awaiting_payment".
Preview current price (optional)
POST /api/v1/flights/get_order_quote — returns the current confirmed price and whether the
hold is still payable. Pass order_id (preferred) or pnr.
Pay and issue tickets
POST /api/v1/flights/pay_order — charges the agency balance and issues tickets. Pass
order_id. Do not send amount or currency — they are resolved server-side.
A held booking is not guaranteed until payment succeeds. pay_order will fail when the PNR
has expired or been cancelled, the hold/payment deadline has passed, or the airline has released
the reservation early. Airlines can expire a hold before the date or time originally returned.
Treat the pay_order response as authoritative, handle failure without charging the traveler,
and run a new search when a fresh booking is required.
GET_FLIGHTS → PRICE_FLIGHT → BOOK_FLIGHT (hold) → [GET_ORDER_QUOTE] → PAY_ORDER → GET_BOOKINGCancelling a held reservation
cancel_order cancels a HELD (unpaid) reservation — it is NOT a refund. It deletes the
reservation and releases the PNR with the airline. It does not apply to issued (paid) tickets
and does not refund anything, because a held reservation was never paid.
Why this matters: if you create a hold and then abandon it, the airline may refuse a new booking for the same passenger on the same route while an un-voided reservation is pending. Always cancel the old hold to release the PNR before re-booking that passenger.
BOOK_FLIGHT (hold) → (changed your mind) → CANCEL_ORDER → PNR released → safe to re-bookPOST /api/v1/flights/cancel_order — pass order_id (preferred) or booking_id.
Post-booking operations (void, exchange, refund)
Self-serve void, exchange, and refund on issued tickets are not yet available through the API. Right now, all post-booking operations on paid/issued bookings — void, exchange, re-issue, and refund — must be submitted to the FX-Port team for manual processing. Email [email protected], or open the booking confirmation page in the FX-Port dashboard and use Request support. That action is available on every booking.
Requests are handled by a dedicated team over multiple channels — in-dashboard support, email, and a direct messaging channel — 24/7, and urgent cases such as same-day voids are actioned immediately.
This limitation applies to issued flight tickets only. Post-booking operations for hotels, transfers, and eSIMs are fully supported through the API. FX-Port is actively building self-serve post-booking endpoints for flights and rolling them out per supplier as airline and GDS access is granted. Until then, do not build a workflow that assumes automated refunds or voids on issued tickets. See Post-booking operations for details.