Flight booking API integration: what the docs leave out

The ticket on your board says "add flights". You have shipped a payments integration, a shipping-rates integration, maybe a maps one, and the mental model you bring is the obvious one: search, show results, take the card, done. Then the first real booking comes back at a different price from the one on the results page, the second one times out and nobody can tell you whether the customer has a seat, and someone in operations asks why there is a reservation but no ticket. A flight booking API integration looks like an e-commerce checkout from the outside. Underneath, it is a distributed transaction against systems that were designed long before REST, and most of the surprises come from that gap.
This is written for the developer who has never seen a PNR. It is not about any one supplier's endpoints; the names change between providers, the shape does not.
The call sequence behind a flight booking API integration
Almost every flight API, whatever it calls its methods, walks the same four steps. Getting the boundaries between them right is most of the work.
| Step | What it gives you | What you must store | What goes wrong |
|---|---|---|---|
| Search | Itineraries with a price and an opaque offer or fare key | Nothing durable — results go stale quickly | You treat the price as final; the key expires before checkout |
| Price / verify | The confirmed price, fare rules, baggage, sometimes required passenger fields | The verified offer and its expiry | Price changed; the class sold out; the rules differ from what you displayed |
| Book | A reservation — the PNR — with a record locator and a ticketing deadline | Your own reference, the locator, the deadline, the exact passenger data sent | Timeout with no answer; duplicate PNRs; names rejected |
| Ticket | Issued e-ticket numbers; this is where money is actually committed | Every ticket number, against the passenger and segment it belongs to | Partial issuance; reservation cancelled by the airline because the deadline passed |
The row people argue with is the third one, because many APIs let you book and ticket in a single call. Use it if you like. The two things are still separate in the airline's world: a PNR can exist without a ticket, and a ticket can fail after the PNR was created. A combined endpoint just hides the moment where one succeeded and the other did not, so your data model should still have a place for that state.
Notice too what search does not return: a promise. It is an advertisement. The price step is the quote, and only the ticket is the sale.
Why the price you searched is not the price you book
Web developers expect a catalogue. Airline inventory is not one. A flight is sold in booking classes, each a bucket of seats at a fare, and the airline opens and closes those buckets continuously as the flight fills. Search results are assembled quickly from availability that may already be a little behind; by the time a user has typed in two passports, the cheapest bucket on that flight may have closed. When the price step runs, it asks again, and the honest answer is sometimes higher.
Taxes add their own drift. They are recalculated at pricing for the exact passengers and route, and a child or an infant prices differently from the adult the search assumed. Currency conversion, if your storefront shows a currency other than the one the supplier quotes in, is one more place the number moves.
The design consequence is simple and often skipped: never charge on the search price. Run the price step before payment, compare, and if the amount changed, show the new number and ask. Whatever markup you apply has to be recalculated on the repriced fare, not carried over from the results page — the logic is the same one an agency works through in setting a markup strategy online, and it breaks the same way when the base moves underneath it.
Idempotency, and what a timeout during booking means
This is the section to read twice.
When a booking call times out, you do not know what happened. The request may never have arrived. It may have arrived and failed. Or — the case that hurts — it arrived, the supplier created the PNR with the airline, and the response was lost on its way back to you. To your code, all three look identical. To the airline, the third one is a live reservation holding seats under your customer's name.
The reflex from other integrations is to retry. Here, a blind retry can produce a second PNR for the same passengers on the same flight. Airlines treat duplicate bookings as a policy violation; depending on the carrier and the agency's agreements, the consequence ranges from automatic cancellation of one or both reservations to a debit memo — an ADM — sent to whoever issued them. The agency that receives it will want to know why your system booked twice.
What works, in roughly this order:
- Create your own booking reference before calling out, persist it, and send it with the request wherever the API accepts a client reference. If the API supports an idempotency key, use it; if it does not, your reference is still what lets you search for the booking afterwards.
- Model the unknown state explicitly. Pending, confirmed, failed — and unknown. A timeout moves a booking to unknown, not to failed.
- Resolve unknown by asking, not by repeating. Retrieve by your reference, or list recent bookings for those passengers, before deciding whether to try again.
- Run a reconciliation job that sweeps anything still unknown and compares it with what the supplier reports, and route what it cannot settle to a human queue rather than guessing.
Ticketing timeouts are the same problem with money attached. If you capture the card before ticketing and ticketing hangs, you have a paid customer and possibly no ticket. If you ticket before capture and the capture fails, you have issued a document someone has to pay the airline for. Authorising the card first, ticketing, then capturing on success is the common shape — the point is to decide it deliberately, not discover it in production.
The travel concepts that surprise web developers
None of these is hard. Each one has cost somebody a week because they did not know it existed.
A PNR is not a ticket
The PNR is the reservation record: passengers, segments, contacts, a deadline. The ticket is the paid document that entitles the passenger to fly. An unticketed PNR expires at its ticketing deadline and the seats go back on sale, sometimes silently from your point of view.
Names are close to immutable
After ticketing, most fares do not allow a name change beyond a minor correction, and the rules for what counts as minor vary by airline. The name has to match the travel document. Collect surname and given names separately, do not let a free-text title leak into a name field, and validate before the book call, not after.
Passenger types are priced, not decorative
Adult, child and infant are fare types, and the age that decides which applies is usually the age on the date of travel, not on the booking date. An infant on a lap typically occupies no seat and may only travel with an adult. Get the type wrong and the price step either fails or quotes the wrong fare.
Times are local, and segments are not legs
Departure and arrival times are given in the local time of each airport. Do not convert them to the user's time zone for display, and do not compute durations by subtracting them without the offsets. A journey contains segments; a segment with a technical stop contains more than one leg. Your UI and your data need to agree on which of those a "stop" is.
Things happen after the sale
Airlines change schedules after tickets are issued. A booking that was correct at ticketing can show a new time, a new flight number or a broken connection weeks later, and depending on the supplier you learn about it through a notification, a queue or by retrieving the booking again. Plan for the booking to change after you have stopped looking at it.
Void is not refund
Shortly after issuance there is usually a window in which a ticket can be voided as though it never existed. After that window, only a refund under the fare rules is possible, and it may cost a penalty or return nothing at all. The window and its rules belong to the supplier and the issuing agreement; read them before you build a "cancel" button.
What getting it wrong costs
The failures in a flight integration are expensive in a specific way: they land on people, not on logs. A duplicate booking becomes a phone call to the airline and possibly a memo against the agency's account. A charged customer without a ticket becomes a refund, a complaint and a chargeback risk. A ticket issued without a successful payment becomes a debt to the airline someone has to settle. A schedule change nobody processed becomes a traveller at the airport for a flight that left earlier.
None of those shows up in a happy-path test. Write the unhappy paths first: the timeout during book, the price that rose, the ticket that failed after the PNR, the void after a successful payment. If those are handled, the happy path is the easy part.
Testing against a flight API
Supplier test environments are useful and incomplete. They tend to be quieter than production, so sold-out classes and price changes are rarer, and some of them do not simulate timeouts at all. Use them for the shape of the calls and the validation errors, then plan a controlled run in production with real bookings you void inside the window — with operations aware that you are doing it.
Whether to integrate at all is a separate question. If what you really need is a storefront rather than raw inventory in your own system, the trade-off is laid out in white label versus building your own booking engine, and the same reasoning applies to a B2B portal for sub-agents. If you do want the inventory in your own code, this platform exposes flight and hotel APIs, and access starts with a conversation about your use case rather than a self-serve key — which is also the right moment to ask each of the questions above.