Flight API conventions
The success and error envelopes, money, local and UTC times, ids and offer references.
Every endpoint lives under /v1/flight. Success, failure, money and time follow the same rules on every route.
Success
Every success is wrapped:
{ "data": … }The bookings list adds a sibling meta for pagination:
{ "data": [ … ], "meta": { "pagination": { "limit": 20, "offset": 0, "has_more": false, "total": 2 } } }The airline and airport lists add meta.truncated instead: there is no next page, so raise limit or narrow q.
Offers add meta.supplier, which names who priced the fares, and only when they apply meta.truncated and meta.unsupported_filters, so their presence always means something. On a fresh SDK prebook you receive meta.payment_sdk with provider and token; LiteAPI also includes environment. A validated LiteAPI replay while ready to book can return the same metadata on 200. OEX replay, get, list and book omit it, so choose the SDK using the provider returned at prebook.
Errors
Every failure is one error object with a code, a reason, a message and the request_id; the tables are in Flight API errors.
Money
Money is always an object in major units:
{ "amount": 506.73, "currency": "USD" }506.73 is five hundred and six dollars and seventy-three cents.
Time
Timestamps are RFC 3339 in UTC (2026-11-01T12:34:56.000Z).
Flight departure and arrival times are the exception. They are the airport's local time with no offset (2026-11-10T06:58:00), because that is what a ticket shows. Parse them as local civil time, not UTC. Dates are YYYY-MM-DD.
Ids
Ids we mint carry a prefix that says what they are: bkg_ a booking, psg_ a passenger, svc_ an extra on a booking, a bag or a seat, aln_ an airline, apt_ an airport. They are stable and safe to store. supplier_reference is the supplier's order id and airline_pnr the airline's record locator; both come from outside and are what a traveller quotes at a desk.
Offer references
Every priced offer carries an offer_reference. It is an opaque signed token. Treat it as a blob; do not parse or construct one.
It is the only handle you can prebook from, and it expires at the offer's expires_at. Offers are not stored on our side: if you lose the reference, request offers again.