{"openapi":"3.0.0","info":{"title":"API: Flights","version":"3.0.0","description":"The Flights API provides endpoints for searching flights, managing bookings, and accessing static flight data including airlines and airports."},"servers":[{"url":"https://api.liteapi.travel/v3.0"}],"security":[{"apikeyAuth":[]}],"components":{"securitySchemes":{"apikeyAuth":{"name":"X-API-Key","type":"apiKey","in":"header"}},"schemas":{"Airline":{"type":"object","properties":{"active":{"type":"boolean","description":"Whether the airline is currently active"},"alliance":{"type":"string","description":"Airline alliance membership (star_alliance, oneworld, skyteam, vanilla_alliance)"},"callsign":{"type":"string","description":"Airline callsign"},"country":{"type":"string","description":"Country of origin"},"iata":{"type":"string","description":"2-letter IATA airline code"},"icao":{"type":"string","description":"3-letter ICAO airline code"},"logo":{"type":"string","description":"URL to airline logo"},"name":{"type":"string","description":"Airline name"}},"description":"Full airline details including name, codes, alliance, and logo"},"AirlineIATA":{"type":"object","properties":{"iata":{"type":"string","description":"2-letter IATA airline code"},"name":{"type":"string","description":"Airline name"}},"description":"Minimal airline representation with IATA code and name"},"Airport":{"type":"object","properties":{"city":{"type":"string","description":"City name"},"country":{"type":"string","description":"Country name"},"iata":{"type":"string","description":"3-letter IATA airport code"},"icao":{"type":"string","description":"4-letter ICAO airport code"},"lat":{"type":"number","description":"Latitude"},"lon":{"type":"number","description":"Longitude"},"name":{"type":"string","description":"Airport name"},"state":{"type":"string","description":"State or province"},"tz":{"type":"string","description":"Timezone (e.g., America/New_York)"}},"description":"Full airport details including location, codes, and timezone"},"AirportIATA":{"type":"object","properties":{"iata":{"type":"string","description":"3-letter IATA airport code"},"name":{"type":"string","description":"Airport name"}},"description":"Minimal airport representation with IATA code and name"},"FlightSegment":{"type":"object","properties":{"arrivalTime":{"type":"string","description":"Arrival time (ISO 8601)"},"carrier":{"type":"object","properties":{"marketingCode":{"type":"string","description":"Marketing carrier IATA code"},"marketingLogo":{"type":"string","description":"Marketing carrier logo path/URL"},"marketingName":{"type":"string","description":"Marketing carrier name"},"operatingCode":{"type":"string","description":"Operating carrier IATA code"},"operatingLogo":{"type":"string","description":"Operating carrier logo path/URL"},"operatingName":{"type":"string","description":"Operating carrier name"}},"description":"Marketing and operating carrier details for this segment"},"departureTime":{"type":"string","description":"Departure time (ISO 8601)"},"destinationCode":{"type":"string","description":"Destination IATA code"},"direction":{"type":"string","description":"OUTBOUND or INBOUND"},"duration":{"type":"object","properties":{"iso8601":{"type":"string","description":"Duration in ISO 8601 format (e.g. PT7H45M)"},"minutes":{"type":"integer","description":"Duration in minutes"}},"description":"Flight duration in ISO 8601 and minutes"},"flight":{"type":"object","properties":{"marketingNumber":{"type":"string","description":"Flight number as marketed to passengers"},"operatingNumber":{"type":"string","description":"Flight number as operated by the carrier"}},"description":"Marketing and operating flight numbers"},"originCode":{"type":"string","description":"Origin IATA code"},"originName":{"type":"string","description":"Full name of the origin airport"},"destinationName":{"type":"string","description":"Full name of the destination airport"},"segmentKey":{"type":"string","description":"Unique identifier for this segment, used to link with offers, fares, and amenities"}},"description":"A single flight segment (one takeoff and landing) within a journey"},"FlightPrice":{"type":"object","properties":{"base":{"type":"number","description":"Base fare amount (before taxes and fees)"},"currency":{"type":"string","description":"ISO 4217 currency code"},"fees":{"type":"number","description":"Service fees and surcharges"},"taxes":{"type":"number","description":"Total taxes applied to the fare"},"total":{"type":"number","description":"Total price (base + taxes + fees)"},"perPassenger":{"type":"object","properties":{"adult":{"type":"object","properties":{"base":{"type":"number","description":"Base fare for this passenger type"},"currency":{"type":"string","description":"ISO 4217 currency code"},"fees":{"type":"number","description":"Fees for this passenger type"},"taxes":{"type":"number","description":"Taxes for this passenger type"},"total":{"type":"number","description":"Total price for this passenger type"}},"description":"Price breakdown for each adult passenger"},"child":{"type":"object","properties":{"base":{"type":"number","description":"Base fare for this passenger type"},"currency":{"type":"string","description":"ISO 4217 currency code"},"fees":{"type":"number","description":"Fees for this passenger type"},"taxes":{"type":"number","description":"Taxes for this passenger type"},"total":{"type":"number","description":"Total price for this passenger type"}},"description":"Price breakdown for each child passenger"},"infant":{"type":"object","properties":{"base":{"type":"number","description":"Base fare for this passenger type"},"currency":{"type":"string","description":"ISO 4217 currency code"},"fees":{"type":"number","description":"Fees for this passenger type"},"taxes":{"type":"number","description":"Taxes for this passenger type"},"total":{"type":"number","description":"Total price for this passenger type"}},"description":"Price breakdown for each infant passenger"}},"description":"Price breakdown per passenger type"}},"description":"Full price breakdown including base fare, taxes, fees, and per-passenger amounts"},"FlightOffer":{"type":"object","properties":{"offerId":{"type":"string","description":"Unique offer identifier"},"expiration":{"type":"string","description":"Offer expiration time (ISO 8601)"},"pricing":{"$ref":"#/components/schemas/FlightOfferPricing","description":"Pricing breakdown with FX conversion details"},"fare":{"type":"object","properties":{"family":{"type":"string","description":"Fare family name (e.g. Economy, Business, First)"},"mixedCabin":{"type":"boolean","description":"True if outbound and inbound legs are in different cabin classes"},"seatsRemaining":{"type":"integer","description":"Number of seats remaining at this fare"}},"description":"Fare class information"},"terms":{"type":"object","properties":{"changeable":{"type":"boolean","description":"True if the fare allows changes (rebooking)"},"refundable":{"type":"boolean","description":"True if the fare is refundable"},"summary":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","description":"Severity: info, warning, or danger"},"message":{"type":"string","description":"Policy message text (e.g. Non-refundable, Changes allowed with fee)"}}},"description":"Human-readable policy messages with severity levels"},"changeFee":{"$ref":"#/components/schemas/FlightFee","description":"Change fee details; null when the provider does not publish a fee"},"refundFee":{"$ref":"#/components/schemas/FlightFee","description":"Refund/cancellation fee details; null when the provider does not publish a fee"},"hasChangeFee":{"type":"boolean","description":"True when the provider signalled that a change fee applies to the fare, even when the actual amount is not published in `changeFee`. Lets clients render a \"change fee applies — amount on request\" remark for fares where the rule is known but the monetary amount is not exposed (common for LCC content distributed via GDS, e.g. U2 / easyJet via Sabre). When `false` or absent, no change fee is known to apply."},"hasRefundFee":{"type":"boolean","description":"True when the provider signalled that a refund/cancellation fee applies to the fare, even when the actual amount is not published in `refundFee`. Lets clients render a \"cancellation fee applies — amount on request\" remark for fares where the rule is known but the monetary amount is not exposed. When `false` or absent, no refund fee is known to apply."}},"description":"Booking terms and conditions for this offer"},"baggage":{"type":"object","description":"Baggage policy for this offer","properties":{"hasCarryOnBag":{"type":"boolean","description":"Whether carry-on bag is included"},"hasCheckedBag":{"type":"boolean","description":"Whether checked bag is included"},"included":{"type":"array","description":"List of included baggage allowances","items":{"type":"object","properties":{"bagType":{"type":"string","enum":["cabin","checked"],"description":"Type of bag"},"description":{"type":"string","description":"Human-readable baggage description"},"passengerType":{"type":"string","enum":["ADT","CHD","INF"],"description":"Passenger type this allowance applies to"},"pieces":{"type":"integer","description":"Number of pieces allowed"},"pricing":{"$ref":"#/components/schemas/FlightItemPricing","description":"Cost if not free (amount 0 means included)"},"unit":{"type":"string","description":"Weight unit (e.g. kg)"},"weightKg":{"type":"number","description":"Weight limit in kg"}}}}}},"segmentFares":{"type":"array","description":"Per-segment fare details","items":{"type":"object","properties":{"bookingCode":{"type":"string","description":"Booking/RBD class code (e.g. W, Y, J)"},"cabin":{"type":"string","description":"Cabin class (e.g. Economy, Business, First)"},"fareBasisCode":{"type":"string","description":"Fare basis code"},"fareFamily":{"type":"string","description":"Fare family name"},"seatsRemaining":{"type":"integer","description":"Number of seats remaining at this fare"},"segmentKey":{"type":"string","description":"Links to the segment this fare applies to"}}}},"segmentAmenities":{"type":"array","description":"Per-segment amenity data (each entry linked by segmentKey)","items":{"$ref":"#/components/schemas/FlightSegmentAmenities"}}},"description":"A bookable offer for a journey, including pricing, baggage policy, fare details, and booking terms"},"FlightSegmentAmenities":{"type":"object","description":"Amenities for a specific segment (linked by segmentKey)","properties":{"aircraftType":{"type":"string","description":"Aircraft model for this segment","example":"Boeing 787-9"},"amenities":{"type":"array","description":"List of amenities available on this segment","items":{"$ref":"#/components/schemas/FlightAmenity"}},"segmentKey":{"type":"string","description":"Links to the segment this amenities data belongs to (matches segment.segmentKey)","example":"a3f2b1c9"}}},"FlightAmenity":{"type":"object","description":"A single in-flight amenity for a segment","properties":{"available":{"type":"boolean","description":"Whether this amenity is offered on this segment","example":true},"category":{"type":"string","enum":["wifi","power","entertainment","food","seat_comfort"],"description":"Amenity category","example":"wifi"},"chargeable":{"type":"boolean","nullable":true,"description":"True if paid, False if free, null if unknown","example":true},"details":{"type":"string","nullable":true,"description":"Additional details (e.g. 'Streaming only', '34 inch pitch')","example":"Available for purchase"},"name":{"type":"string","description":"Human-readable amenity name","example":"Wi-Fi"}}},"FlightJourney":{"type":"object","properties":{"journeyKey":{"type":"string","description":"Unique identifier for this journey (hash of route, flights, and times)"},"isCheapest":{"type":"boolean","description":"True if this is the cheapest journey across all results"},"cheapestOffer":{"$ref":"#/components/schemas/FlightOffer","description":"Quick reference to the lowest-priced offer for this journey"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/FlightOffer"},"description":"All available provider offers for this journey, sorted by price ascending"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/FlightSegment"},"description":"Ordered list of flight segments that make up this journey"},"parameters":{"type":"object","properties":{"adults":{"type":"integer","description":"Number of adult passengers"},"children":{"type":"integer","description":"Number of child passengers"},"infants":{"type":"integer","description":"Number of infant passengers"}},"description":"Passenger composition used in the search that produced this journey"},"timestamp":{"type":"string","description":"UTC timestamp when this journey was retrieved from the provider"},"legDurations":{"type":"array","items":{"$ref":"#/components/schemas/FlightLegDuration"},"description":"Per-direction elapsed times including layovers (outbound and/or inbound)"},"totalDuration":{"$ref":"#/components/schemas/FlightDuration","description":"Total elapsed time from first departure to last arrival, including all layovers"},"connections":{"type":"array","items":{"$ref":"#/components/schemas/FlightConnection"},"description":"Layover details between consecutive segments"}},"description":"A complete journey (one or more segments) with all available offers"},"FlightDuration":{"type":"object","properties":{"iso8601":{"type":"string","example":"PT2H30M","description":"Duration in ISO 8601 format (e.g. PT2H30M)"},"minutes":{"type":"integer","example":150,"description":"Duration in minutes"}},"description":"Duration expressed in both ISO 8601 format and minutes"},"FlightMatrixCell":{"type":"object","description":"Cheapest-price summary for a single departure/return date combination.","properties":{"outboundDate":{"type":"string","format":"date","description":"Departure date for this cell (YYYY-MM-DD).","example":"2026-08-26"},"outboundOffset":{"type":"integer","description":"Days from the requested departure date (-flexDays..+flexDays).","example":0},"returnDate":{"type":"string","format":"date","nullable":true,"description":"Return date for this cell (YYYY-MM-DD). Null for one-way searches.","example":"2026-09-03"},"returnOffset":{"type":"integer","nullable":true,"description":"Days from the requested return date (-flexDays..+flexDays). Null for one-way searches.","example":0},"price":{"type":"number","format":"float","nullable":true,"description":"Cheapest display total for this date combination (includes rate-search margin). Null when no priced offer was found.","example":491.81},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency of the cell price. Null when no priced offer was found.","example":"EUR"},"success":{"type":"boolean","description":"True when the underlying search returned at least one priced offer for this combination."},"cached":{"type":"boolean","description":"True when the underlying search was served from cache."}}},"FlightMatrixData":{"type":"object","description":"Flexible-date price matrix: cheapest fare per date combination around the requested dates.","properties":{"baseOutboundDate":{"type":"string","format":"date","description":"The originally requested departure date (YYYY-MM-DD).","example":"2026-08-26"},"baseReturnDate":{"type":"string","format":"date","nullable":true,"description":"The originally requested return date. Null for one-way searches.","example":"2026-09-03"},"cells":{"type":"array","description":"One cell per valid date combination, sorted by (outboundOffset, returnOffset).","items":{"$ref":"#/components/schemas/FlightMatrixCell"}},"cheapest":{"allOf":[{"$ref":"#/components/schemas/FlightMatrixCell"}],"nullable":true,"description":"The globally cheapest cell across the whole grid. Null when no cell was priced."},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency of the global cheapest cell. Null when nothing was priced.","example":"EUR"},"flexDays":{"type":"integer","description":"Effective flexibility window applied (1-3).","example":3},"roundTrip":{"type":"boolean","description":"True when the request was a round-trip (return dates vary across columns)."},"totalCells":{"type":"integer","nullable":true,"description":"Total number of date combinations in the grid. Present on matrix-start SSE events; omitted from the non-streaming JSON response."}}},"FlightMatrixResponse":{"type":"object","description":"Response for POST /flights/rates/matrix.","required":["data"],"properties":{"data":{"type":"array","description":"Matrix result sets (one element for this endpoint).","items":{"$ref":"#/components/schemas/FlightMatrixData"}}}},"FlightLegDuration":{"type":"object","properties":{"dayChange":{"type":"integer","description":"Number of calendar days added crossing midnight (0 = same day arrival, 1 = next day, etc.)","example":1},"direction":{"type":"string","enum":["OUTBOUND","INBOUND"],"description":"Which leg this duration applies to","example":"OUTBOUND"},"duration":{"$ref":"#/components/schemas/FlightDuration","description":"Elapsed time for this leg including all layovers"},"overnightFlight":{"type":"boolean","description":"True if the flight departs and arrives on different calendar days","example":false}},"description":"Total elapsed time for one direction of a journey (outbound or inbound), including layovers"},"FlightMoneyAmount":{"type":"object","properties":{"amount":{"type":"number","description":"Monetary amount"},"currency":{"type":"string","description":"ISO 4217 currency code"}},"description":"A monetary amount with currency"},"FlightItemPricing":{"type":"object","properties":{"display":{"$ref":"#/components/schemas/FlightMoneyAmount","description":"Customer-facing amount (converted to search currency if applicable)"},"converted":{"type":"boolean","description":"True if FX currency conversion was applied"}},"description":"Pricing for an ancillary item (e.g. baggage)"},"FlightFee":{"type":"object","nullable":true,"description":"Change or refund fee published by the provider. Null when the provider does not publish a fee.","properties":{"pricing":{"type":"object","nullable":true,"description":"Fee pricing; null when only a percentage is available","properties":{"display":{"$ref":"#/components/schemas/FlightMoneyAmount","description":"Customer-facing fee amount after FX conversion and margin"},"converted":{"type":"boolean","description":"True when FX conversion was applied"}}},"percent":{"type":"number","nullable":true,"description":"Fee as a percentage of the base fare (e.g. 100 = full penalty). May appear without pricing."},"applicability":{"type":"string","enum":["anytime","noShow","beforeDeparture","afterDeparture"],"description":"When the fee applies"},"label":{"type":"string","description":"Human-readable fee description (e.g. 'Change fee (before departure)')"}}},"FlightBookedService":{"type":"object","description":"Ancillary service (seat, baggage, etc.) that has been attached to a booking and confirmed by the provider. Returned under booking.bookedServices after /services or /bookings.","required":["serviceId","pricing"],"properties":{"serviceId":{"type":"string","description":"Encoded service identifier (carries provider serviceId, post-margin price, currency, category)"},"name":{"type":"string","description":"Human-readable service name (e.g. 'Seat 1A')"},"category":{"type":"string","description":"Service category (e.g. 'seat', 'baggage')"},"passengerType":{"type":"string","description":"Applicable passenger type (ALL, ADT, CHD, INF)"},"passengerIndex":{"type":"integer","description":"Index of the passenger this service applies to (0-based; matches the passengers[] array)"},"segmentKey":{"type":"string","description":"The flight segment this service applies to (matches journey.segments[].segmentKey)"},"quantity":{"type":"integer","description":"Number of units booked"},"createdAt":{"type":"string","format":"date-time","description":"UTC timestamp when the provider attached the service"},"phase":{"type":"string","description":"Provider phase, e.g. 'post_booking'"},"status":{"type":"string","description":"Provider status of this service, e.g. 'pending', 'confirmed'"},"pricing":{"$ref":"#/components/schemas/FlightItemPricing","description":"Customer-facing price for this service (post-margin)"},"metadata":{"type":"object","description":"Category-specific metadata. Contains exactly one of `seat` (when category is 'seat') or `baggage` (when category is 'baggage').","properties":{"seat":{"type":"object","description":"Seat details — present only when category is 'seat'","properties":{"available":{"type":"boolean","description":"Whether this seat is currently available"},"position":{"type":"string","description":"Physical position (window, middle, aisle)"},"seatColumn":{"type":"string","description":"Column letter (e.g. A, B, C)"},"seatNumber":{"type":"string","description":"Full seat label (e.g. 1A)"},"seatRow":{"type":"integer","description":"Row number"},"seatType":{"type":"string","description":"Seat class/type (standard, extra_legroom, exit_row, ...)"}}},"baggage":{"type":"object","description":"Baggage details — present only when category is 'baggage'","properties":{"bagType":{"type":"string","description":"Type of bag (e.g. checked, cabin)"},"pieces":{"type":"integer","description":"Number of bag pieces booked"},"weightKg":{"type":"number","description":"Weight allowance in kilograms"}}}}}}},"FlightOfferPricing":{"type":"object","properties":{"display":{"$ref":"#/components/schemas/FlightPrice","description":"Customer-facing price breakdown (converted to search currency if applicable)"},"converted":{"type":"boolean","description":"True if FX currency conversion was applied"}},"description":"Full offer pricing with per-passenger breakdown"},"FlightFullOfferPricing":{"type":"object","description":"Offer pricing for the verify journey and changes: customer-facing display price.","required":["display","converted"],"properties":{"display":{"$ref":"#/components/schemas/FlightPrice","description":"Customer-facing price"},"converted":{"type":"boolean","description":"Whether FX currency conversion was applied"}}},"FlightChangesPricing":{"type":"object","description":"Pricing comparison between search and verification (provider ChangesPricing).","required":["old","new"],"properties":{"old":{"$ref":"#/components/schemas/FlightFullOfferPricing","description":"Pricing from the original search"},"new":{"$ref":"#/components/schemas/FlightFullOfferPricing","description":"Pricing from the verified offer"}}},"FlightVerifyChanges":{"type":"object","description":"Changes detected between search and verification.","properties":{"cabinChanged":{"type":"boolean","description":"True if cabin class changed"},"fareChanged":{"type":"boolean","description":"True if fare class/booking code changed"},"messages":{"type":"array","items":{"type":"string"},"description":"Human-readable list of change descriptions"},"newCabin":{"type":"string","nullable":true,"description":"Current cabin class"},"newFareClass":{"type":"string","nullable":true,"description":"Current booking code"},"newFareFamily":{"type":"string","nullable":true,"description":"Current fare brand"},"oldCabin":{"type":"string","nullable":true,"description":"Original cabin class"},"oldFareClass":{"type":"string","nullable":true,"description":"Original booking code (e.g., Y, M)"},"oldFareFamily":{"type":"string","nullable":true,"description":"Original fare brand (e.g., Economy Light)"},"priceChanged":{"type":"boolean","description":"True if price has changed"},"pricing":{"$ref":"#/components/schemas/FlightChangesPricing","nullable":true,"description":"Full pricing comparison (search vs verified); use instead of legacy currency/price scalars"}}},"FlightVerifyJourney":{"type":"object","description":"Journey in verify response. The `offerId` is not returned in the JSON body (use the same id you sent on the verify request for prebook/book).","properties":{"journeyKey":{"type":"string","description":"Unique identifier for this journey"},"expiration":{"type":"string","description":"Offer expiration time (ISO 8601)"},"timestamp":{"type":"string","description":"When the journey was generated (ISO 8601)"},"provider":{"type":"object","description":"Flight provider information","properties":{"code":{"type":"string","description":"Provider code (e.g. SABRE, TRAVELPORT, ATLAS, FLIGHTHUB)"},"logo":{"type":"string","description":"URL to provider logo"}}},"pricing":{"$ref":"#/components/schemas/FlightFullOfferPricing","description":"Offer pricing with original (provider) and display (customer) breakdown per provider FlattenedJourney"},"baggage":{"type":"object","description":"Baggage policy for this offer","properties":{"hasCarryOnBag":{"type":"boolean","description":"True if a carry-on bag is included in this offer"},"hasCheckedBag":{"type":"boolean","description":"True if a checked bag is included in this offer"},"included":{"type":"array","items":{"type":"object","properties":{"bagType":{"type":"string","enum":["cabin","checked"],"description":"Type of bag: cabin (carry-on) or checked"},"description":{"type":"string","description":"Human-readable baggage allowance description"},"passengerType":{"type":"string","enum":["ADT","CHD","INF"],"description":"Passenger type this allowance applies to (ADT, CHD, INF)"},"pieces":{"type":"integer","description":"Number of bag pieces allowed"},"pricing":{"$ref":"#/components/schemas/FlightItemPricing","description":"Cost of this baggage allowance; amount 0 means included at no charge"},"unit":{"type":"string","description":"Weight unit (e.g. kg)"},"weightKg":{"type":"number","description":"Maximum weight per bag in kg"}}},"description":"List of included baggage allowances per passenger type"}}},"fare":{"type":"object","properties":{"family":{"type":"string","description":"Fare family name (e.g. Economy, Business, First)"},"mixedCabin":{"type":"boolean","description":"True if outbound and inbound legs are in different cabin classes"},"seatsRemaining":{"type":"integer","description":"Number of seats remaining at this fare"}},"description":"Fare class information"},"passengers":{"type":"object","description":"Passenger counts for this journey","properties":{"adults":{"type":"integer","description":"Number of adult passengers"},"children":{"type":"integer","description":"Number of child passengers"},"infants":{"type":"integer","description":"Number of infant passengers"}}},"segments":{"type":"array","items":{"$ref":"#/components/schemas/FlightSegment"},"description":"Ordered list of flight segments for this journey"},"segmentFares":{"type":"array","description":"Per-segment fare details","items":{"type":"object","properties":{"bookingCode":{"type":"string","description":"Booking/RBD class code (e.g. W, Y, J)"},"cabin":{"type":"string","description":"Cabin class (e.g. Economy, Business, First)"},"fareBasisCode":{"type":"string","description":"Fare basis code used for pricing and rules"},"fareFamily":{"type":"string","description":"Commercial fare family name"},"seatsRemaining":{"type":"integer","description":"Number of seats remaining at this fare"},"segmentKey":{"type":"string","description":"Links this fare to the corresponding segment"}}}},"terms":{"type":"object","properties":{"changeable":{"type":"boolean","description":"True if the fare allows changes (rebooking)"},"refundable":{"type":"boolean","description":"True if the fare is refundable"},"summary":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","description":"Severity: info, warning, or danger"},"message":{"type":"string","description":"Policy message text"}}},"description":"Human-readable policy messages with severity levels"},"changeFee":{"$ref":"#/components/schemas/FlightFee","description":"Change fee details; null when the provider does not publish a fee"},"refundFee":{"$ref":"#/components/schemas/FlightFee","description":"Refund/cancellation fee details; null when the provider does not publish a fee"},"hasChangeFee":{"type":"boolean","description":"True when the provider signalled that a change fee applies to the fare, even when the actual amount is not published in `changeFee`. Lets clients render a \"change fee applies — amount on request\" remark for fares where the rule is known but the monetary amount is not exposed. When `false` or absent, no change fee is known to apply."},"hasRefundFee":{"type":"boolean","description":"True when the provider signalled that a refund/cancellation fee applies to the fare, even when the actual amount is not published in `refundFee`. Lets clients render a \"cancellation fee applies — amount on request\" remark for fares where the rule is known but the monetary amount is not exposed. When `false` or absent, no refund fee is known to apply."}},"description":"Booking terms and conditions for this offer"}}},"FlightBooking":{"type":"object","description":"Flight booking details (maps to provider BookingData)","properties":{"bookingId":{"type":"string","description":"Unique booking identifier"},"bookingRef":{"type":"string","description":"FlightHub booking reference (FH-YYM-XXXXXXXX)"},"status":{"type":"string","description":"Booking status: PENDING_CONFIRMATION, CONFIRMED, CANCELLED, PENDING, TICKETED"},"timestamp":{"type":"string","description":"Booking creation time (UTC)"},"offerId":{"type":"string","description":"Offer ID from verify stage"},"paymentStatus":{"type":"string","description":"Payment status: pending, completed, failed, not_required"},"distributorCommission":{"type":"number","description":"Commission amount for the distributor."},"distributorPrice":{"type":"number","description":"Price after distributor commission."},"providerEnvironment":{"type":"string","enum":["sandbox","production"],"description":"Provider environment used for this booking (sandbox or production)"},"ticketLimitTime":{"type":"string","format":"date-time","description":"Deadline for ticket issuance (UTC)"},"lastRefreshedAt":{"type":"string","format":"date-time","description":"UTC timestamp of the last successful provider API status refresh"},"journey":{"type":"object","properties":{"journeyKey":{"type":"string","description":"Unique journey identifier"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/FlightSegment"},"description":"Flight segments in this booking"},"price":{"$ref":"#/components/schemas/FlightPrice","description":"Journey price at time of booking"},"pricing":{"$ref":"#/components/schemas/FlightOfferPricing","description":"Journey pricing (provider FlattenedJourney.pricing)"},"baggage":{"type":"object","description":"Fare baggage allowance on the booked journey (included and paid options; aligns with provider FlattenedJourney.baggage)","properties":{"hasCarryOnBag":{"type":"boolean","description":"Whether carry-on bag is included"},"hasCheckedBag":{"type":"boolean","description":"Whether checked bag is included"},"included":{"type":"array","description":"Baggage included in the fare","items":{"type":"object","properties":{"bagType":{"type":"string","enum":["cabin","checked","personal"]},"description":{"type":"string"},"passengerType":{"type":"string","enum":["ADT","CHD","INF","ALL"]},"pieces":{"type":"integer"},"pricing":{"$ref":"#/components/schemas/FlightItemPricing"},"size":{"type":"string"},"unit":{"type":"string"},"weightKg":{"type":"number"}}}},"paid":{"type":"array","description":"Available paid baggage options","items":{"type":"object","properties":{"bagType":{"type":"string","enum":["cabin","checked","personal"]},"description":{"type":"string"},"passengerType":{"type":"string","enum":["ADT","CHD","INF","ALL"]},"pieces":{"type":"integer"},"pricing":{"$ref":"#/components/schemas/FlightItemPricing"},"size":{"type":"string"},"unit":{"type":"string"},"weightKg":{"type":"number"}}}}}},"terms":{"type":"object","nullable":true,"description":"Booking terms from the provider","properties":{"changeable":{"type":"boolean"},"refundable":{"type":"boolean"},"summary":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string"},"message":{"type":"string"}}}},"changeFee":{"$ref":"#/components/schemas/FlightFee","description":"Change fee details; null when the provider does not publish a fee"},"refundFee":{"$ref":"#/components/schemas/FlightFee","description":"Refund/cancellation fee details; null when the provider does not publish a fee"},"hasChangeFee":{"type":"boolean"},"hasRefundFee":{"type":"boolean"}}}},"description":"Journey details as confirmed by the provider at booking time"},"passengers":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Passenger type code (ADT, CHD, INF)"},"title":{"type":"string","description":"Passenger title (Mr, Mrs, Ms, etc.)"},"firstName":{"type":"string","description":"Passenger first name as on travel document"},"lastName":{"type":"string","description":"Passenger last name as on travel document"},"middleName":{"type":"string","description":"Passenger middle name"},"dateOfBirth":{"type":"string","description":"Date of birth (YYYY-MM-DD)"},"birthday":{"type":"string","format":"date","description":"Date of birth (YYYY-MM-DD)"},"gender":{"type":"string","description":"Passenger gender: M or F"},"nationality":{"type":"string","description":"Passenger nationality as ISO country code"},"passengerType":{"type":"integer","description":"0=Adult, 1=Child, 2=Infant"},"documentType":{"type":"string","description":"Type of travel document (e.g. passport, id_card)"},"documentNumber":{"type":"string","description":"Travel document number"},"documentIssueCountry":{"type":"string","description":"ISO country code of the document issuing country"},"documentExpiry":{"type":"string","description":"Travel document expiry date (YYYY-MM-DD)"}}},"description":"Passenger details as submitted and confirmed by the provider"},"contact":{"type":"object","properties":{"firstName":{"type":"string","description":"Contact first name"},"lastName":{"type":"string","description":"Contact last name"},"middleName":{"type":"string","description":"Contact middle name"},"email":{"type":"string","description":"Contact email address for booking confirmation"},"phoneCountryCode":{"type":"string","description":"Phone country code without + (e.g. 1 for US, 33 for France)"},"phoneNumber":{"type":"string","description":"Phone number without country code"}},"description":"Primary contact person for the booking"},"order":{"type":"object","properties":{"reference":{"type":"object","properties":{"orderId":{"type":"string","description":"Provider order or PNR reference ID"},"provider":{"type":"object","properties":{"code":{"type":"string","description":"Provider code (e.g. SABRE, TRAVELPORT)"},"pnr":{"type":"string","description":"Provider PNR (Passenger Name Record) locator code"}},"description":"Provider-level booking reference (code + PNR)"},"airlineBookings":{"type":"array","items":{"type":"object","properties":{"airlineCode":{"type":"string","description":"Airline IATA code"},"airlineName":{"type":"string","description":"Airline name"},"airlinePnr":{"type":"string","description":"Airline-specific PNR/locator code"},"pnr":{"type":"string","description":"PNR locator code for this airline"}}},"description":"Per-airline booking references and PNR codes"}},"description":"Provider and airline reference identifiers"},"currency":{"type":"string","description":"ISO 4217 currency code for this order"},"status":{"type":"string","description":"Order status from the provider (e.g. ticketed, created)"},"price":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 currency code"},"total":{"type":"number","description":"Total order price"}},"description":"Order price as confirmed by the provider"},"ticketLimitTime":{"type":"string","description":"Deadline for ticket issuance (UTC)"},"timestamp":{"type":"string","description":"UTC timestamp when the order was created"}},"description":"Order and provider confirmation details"},"airlineLocators":{"type":"array","description":"Airline-specific PNR/locator codes","items":{"type":"object","properties":{"airlineCode":{"type":"string","description":"Airline IATA code"},"airlinePnr":{"type":"string","description":"Airline-specific PNR/locator code"}}}},"pricing":{"type":"object","properties":{"subtotal":{"type":"number","description":"Subtotal before ancillary services"},"servicesAmount":{"type":"number","description":"Total cost of attached ancillary services (seats, baggage, etc.)"},"seatsAmount":{"type":"number","description":"Total cost of seat selections"},"baggageAmount":{"type":"number","description":"Total cost of additional baggage"},"totalAmount":{"type":"number","description":"Grand total charged to the customer"},"currency":{"type":"string","description":"ISO 4217 currency code"}},"description":"Billing breakdown for this booking including base fare and any ancillary services"},"payment":{"type":"object","properties":{"amount":{"type":"number","description":"Amount captured for payment"},"currency":{"type":"string","description":"ISO 4217 currency code of the payment"}},"description":"Payment amounts captured for this booking"},"remarks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Remark name or category"},"value":{"type":"string","description":"Remark content"}}},"description":"Reservation remarks or comments from the provider"},"selectedServices":{"type":"array","items":{"$ref":"#/components/schemas/SelectedService"},"description":"Ancillary services attached to this booking (seats, baggage, etc.)"},"bookedServices":{"type":"array","items":{"$ref":"#/components/schemas/FlightBookedService"},"description":"Detailed view of the ancillary services confirmed by the provider for this booking, including pricing and per-passenger / per-segment metadata. Present once /services has been called."},"ticketData":{"type":"object","properties":{"confirmationId":{"type":"string","description":"Ticket confirmation identifier"},"ticketedAt":{"type":"string","description":"UTC timestamp when the ticket was issued"},"provider":{"type":"string","description":"Provider that issued the ticket"},"source":{"type":"string","description":"Source system that generated the ticket"}},"description":"Ticket issuance details from the provider"},"timings":{"type":"object","properties":{"startedAt":{"type":"string","description":"When the booking flow was initiated"},"persistedAt":{"type":"string","description":"When the booking record was saved to the database"},"orderSentAt":{"type":"string","description":"When the order request was sent to the provider"},"pnrReceivedAt":{"type":"string","description":"When the PNR confirmation was received from the provider"},"paymentStartedAt":{"type":"string","description":"When payment capture was initiated"},"paymentCompletedAt":{"type":"string","description":"When payment capture was completed"},"completedAt":{"type":"string","description":"When the full booking flow was completed"}},"description":"Step-by-step UTC timestamps for booking flow observability"},"settings":{"type":"object","description":"Booking settings"},"paymentInput":{"type":"object","description":"Echo of payment submitted when creating the booking; may include additional provider-specific fields","additionalProperties":true,"properties":{"method":{"type":"string","enum":["TRANSACTION_ID","CREDIT"],"description":"How the booking was paid: Stripe (`TRANSACTION_ID`) or credit line (`CREDIT`)"},"transactionId":{"type":"string","description":"Stripe transaction id when `method` is `TRANSACTION_ID`"}}},"customTags":{"type":"object","description":"Optional bag of up to 5 user-defined key/value labels persisted with the booking. Keys must match `^[A-Z0-9_-]+$` (uppercase letters, digits, `-`, `_`). Values are arbitrary strings up to 255 characters. These labels are returned on booking responses and can be used to filter `GET /flights/bookings` via the `customTags=KEY:VALUE,KEY2:VALUE2` query parameter.","maxProperties":5,"additionalProperties":{"type":"string","maxLength":255},"example":{"SOURCE":"GOOGLE","TIER":"GOLD"}}}},"SelectedService":{"type":"object","properties":{"passengerIndex":{"type":"integer","description":"Zero-based index of the passenger this service is for (matches position in passengers array)","example":0},"serviceId":{"type":"string","description":"Service identifier from servicesAttachable.groups[].services[].serviceId","example":"g6Rwc2lk2SQwMTlkMDY3NC1hMzQzLTc0OGEtYmYyYS1jMDk4ZmNjMTk2ZGGhcMtAfB6PXCj1w6Fjo1VTRA=="},"quantity":{"type":"integer","description":"Number of units of this service to attach","example":1}},"description":"An ancillary service selected by a passenger (seat, baggage, etc.)"},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Numeric error code"},"message":{"type":"string","description":"Short error message"},"description":{"type":"string","description":"Detailed error description"},"key":{"type":"string","description":"JSON path to the offending request field (e.g. bodyRequest.offerId, query.airlinePnr). Present on validation and client-input errors; omitted on auth and server-side errors.","example":"bodyRequest.offerId"}},"description":"Error details"}},"description":"Standard error response envelope"},"FlightSortOptionMeta":{"type":"object","description":"Winner reference for a single sort criterion. The `offerId` matches a `journeys[].offers[].offerId` in the same response, allowing fast lookup of the winning offer's full details.","properties":{"journeyKey":{"type":"string","nullable":true,"description":"The journeyKey of the winning journey for this sort criterion"},"offerId":{"type":"string","nullable":true,"description":"The offerId of the winning offer (matches `journeys[].offers[].offerId`). Present for offer-centric criteria (best, price); may be null for journey-centric criteria (duration, stops)."},"price":{"type":"number","description":"Display total price of the winning offer (with margin applied)","example":753.87},"currency":{"type":"string","description":"Currency code of the price (e.g. USD, EUR)","example":"USD"}}},"FlightBookingCreatePayment":{"type":"object","required":["method"],"properties":{"method":{"type":"string","enum":["TRANSACTION_ID","CREDIT"],"description":"Payment method for `POST /flights/bookings`. Set to `TRANSACTION_ID` after Stripe SDK confirmation, or `CREDIT` to bill an enabled credit line (eligibility enforced server-side)."},"transactionId":{"type":"string","description":"Stripe payment intent id. Required when `method` is `TRANSACTION_ID`; omit when `method` is `CREDIT`.","example":"tr_ABCzxy91C-a9W123"}},"description":"Payment for `POST /flights/bookings`. **Stripe:** `method`: `TRANSACTION_ID` and `transactionId` (e.g. `tr_ABCzxy91C-a9W123`). **Credit line:** `method`: `CREDIT` (omit `transactionId`)."},"FlightBookingCreateRequest":{"title":"Create a flight booking","type":"object","required":["prebookId","payment"],"properties":{"prebookId":{"type":"string","description":"The prebookId returned by `POST /flights/prebooks` (prebook must have completed the book step).","example":"019d0674-834d-7db7-9c8b-93fe8e46e7b8"},"payment":{"$ref":"#/components/schemas/FlightBookingCreatePayment"},"customTags":{"type":"object","description":"Optional bag of up to 5 user-defined key/value labels persisted with the booking. Keys must match `^[A-Z0-9_-]+$` (uppercase letters, digits, `-`, `_`). Values are arbitrary strings up to 255 characters. These labels are returned on booking responses and can be used to filter `GET /flights/bookings` via the `customTags=KEY:VALUE,KEY2:VALUE2` query parameter.","maxProperties":5,"additionalProperties":{"type":"string","maxLength":255},"example":{"SOURCE":"GOOGLE","TIER":"GOLD"}}},"description":"Request body to complete a flight booking"},"FlightConnection":{"type":"object","properties":{"arrivalAirportCode":{"type":"string","example":"JFK","description":"IATA code of the airport where the passenger arrives for this connection"},"arrivalAirportName":{"type":"string","example":"John F Kennedy International Airport","description":"Full name of the arrival airport for this connection"},"arrivalTime":{"type":"string","example":"2026-01-20T14:30:00","description":"UTC ISO 8601 arrival time at the connection airport"},"changeAirport":{"type":"boolean","example":true,"description":"True if the passenger must change airports during this connection"},"departureAirportCode":{"type":"string","example":"LGA","description":"IATA code of the airport from which the passenger departs after layover"},"departureAirportName":{"type":"string","example":"LaGuardia Airport","description":"Full name of the departure airport after layover"},"departureTime":{"type":"string","example":"2026-01-20T17:15:00","description":"UTC ISO 8601 departure time from the connection airport"},"direction":{"type":"string","enum":["OUTBOUND","INBOUND"],"description":"Which leg of the journey this connection belongs to (OUTBOUND or INBOUND)"},"duration":{"$ref":"#/components/schemas/FlightDuration","description":"Connection (layover) duration"},"overnight":{"type":"boolean","example":false,"description":"True if the layover crosses midnight (arrival and departure on different calendar days)"}},"description":"Layover details between two consecutive flight segments"}}},"tags":[{"name":"Airlines","description":"Retrieve airline information and IATA codes"},{"name":"Airports","description":"Retrieve airport information and IATA codes"},{"name":"Flight Search","description":"Search for available flights and verify offers"},{"name":"Flight Bookings","description":"Checkout flow: **1.** Create a checkout session (PREBOOK) → **1.2** Attach services to prebook (optional) → **2.** Complete a booking. Also includes retrieving a booking by ID."}],"paths":{"/data/flights/airlines/iatas/{iataCode}":{"get":{"tags":["Airlines"],"summary":"Get airline by IATA code","description":"## Overview\n\nRetrieve full details for a specific airline using its 2-letter IATA code.\n\n## When to Use\n\n- **Airline display** - Show airline name, logo, and alliance for a given IATA code\n- **Flight result enrichment** - Fetch airline details to display alongside search results\n- **Data validation** - Verify an airline code and retrieve its metadata\n\n## What You Get\n\n- **Airline details** including name, IATA/ICAO codes, and country\n- **Alliance membership** (Star Alliance, oneworld, SkyTeam, or Vanilla Alliance)\n- **Logo URL** for displaying the airline's logo in your UI\n- **Active status** indicating whether the airline is currently operating\n\n## Quick Start\n\nProvide the 2-letter IATA code (e.g., `AA` for American Airlines) in the URL path.","parameters":[{"name":"iataCode","in":"path","required":true,"schema":{"type":"string"},"description":"2-letter IATA airline code (e.g., AA)","example":"AA"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"airline":{"$ref":"#/components/schemas/Airline","description":"Airline details for the requested IATA code"}}},"description":"Single airline result"}}},"example":{"data":[{"airline":{"active":true,"alliance":"oneworld","callsign":"AMERICAN","country":"United States","iata":"AA","icao":"AAL","logo":"https://production.nuitee.flights/static/images/airlines/AA.png","name":"American Airlines"}}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":4002,"description":"IATA code is required","message":"required request field is missing or wrong input"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":401,"description":"Authentication failed","message":"unauthorized"}}}}},"404":{"description":"Airline not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":4004,"description":"Airline not found","message":"entity not found"}}}}}}}},"/data/flights/airports/iatas/{iataCode}":{"get":{"tags":["Airports"],"summary":"Get airport by IATA code","description":"## Overview\n\nRetrieve detailed information for a specific airport using its 3-letter IATA code.\n\n## When to Use\n\n- **Airport display** - Show airport name, city, and country for a given IATA code\n- **Flight result enrichment** - Fetch airport details to display alongside origin/destination in search results\n- **Autocomplete validation** - Verify an airport code and retrieve its full details\n\n## What You Get\n\n- **Airport details** including name, city, country, and timezone\n- **IATA and ICAO codes** for the airport\n- **Geographic coordinates** (latitude and longitude)\n- **Country and city** information for display purposes\n\n## Quick Start\n\nProvide the 3-letter IATA code (e.g., `JFK` for John F. Kennedy International) in the URL path.","parameters":[{"name":"iataCode","in":"path","required":true,"schema":{"type":"string"},"description":"3-letter IATA airport code (e.g., JFK)","example":"JFK"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"airport":{"$ref":"#/components/schemas/Airport","description":"Airport details for the requested IATA code"}}},"description":"Single airport result"}}},"example":{"data":[{"airport":{"city":"New York","country":"United States","iata":"JFK","icao":"KJFK","lat":40.63980103,"lon":-73.77890015,"name":"John F Kennedy International Airport","state":"New York","tz":"America/New_York"}}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":4002,"description":"IATA code is required","message":"required request field is missing or wrong input"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":401,"description":"Authentication failed","message":"unauthorized"}}}}},"404":{"description":"Airport not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":4004,"description":"Airport not found","message":"entity not found"}}}}}}}},"/data/flights/airports/iatas":{"get":{"tags":["Airports"],"summary":"List airport IATA codes","description":"## Overview\n\nRetrieve a lightweight list of airport IATA codes with names for autocomplete and lookup purposes.\n\n## When to Use\n\n- **Autocomplete dropdowns** - Populate airport search inputs with a full list of codes and names\n- **Client-side filtering** - Download the full list once and filter locally\n- **Code validation** - Build a lookup table of valid airport codes\n\n## What You Get\n\n- **IATA codes** for all airports in the database\n- **Airport names** paired with each code\n- **Filtered results** when the `q` query parameter is provided\n\n## Quick Start\n\nCall with no parameters to get all airport codes and names. Use the `q` parameter to filter by name or code.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query","example":"JFK"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"airports":{"type":"array","items":{"$ref":"#/components/schemas/AirportIATA"},"description":"List of airport IATA codes and names"}}},"description":"List of airport IATA result sets"}}},"example":{"data":[{"airports":[{"iata":"JFK","name":"John F Kennedy International Airport"},{"iata":"LHR","name":"London Heathrow Airport"}]}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":4002,"description":"Query parameter 'q' is required for airport search","message":"required request field is missing or wrong input"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":401,"description":"Authentication failed","message":"unauthorized"}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":5000,"description":"Failed to retrieve airport codes","message":"unable to process request"}}}}}}}},"/flights/rates":{"post":{"tags":["Flight Search"],"summary":"Search for flights (legs-based itinerary)","description":"## Overview\n\nSearch for available flights with real-time pricing from multiple providers. The itinerary **must** be sent as a non-empty `legs` array. Each leg follows the provider **SearchLeg** shape: required `origin`, `destination`, and `date` (YYYY-MM-DD); optional `direction` (`OUTBOUND` or `INBOUND`); optional per-leg `filters` that override global `filters` for that leg only.\n\n**Not supported:** top-level `origin`, `destination`, `departureDate`, or `returnDate` — use `legs` only.\n\n## When to Use\n\n- **Listings** — live prices for search results UI\n- **One-way, round-trip, or multi-city** — one leg per segment, in order\n- **Filtering** — cabin class, stops, price, refundability, times (globally or per leg)\n- **Streaming** — incremental provider results over SSE\n\n## What You Get\n\n- Offers from multiple providers\n- Itineraries with segments, layovers, and durations\n- Price breakdown (fares, taxes, fees) and baggage hints\n\n## Key Features\n\n- Multi-provider aggregation in one request\n- **SSE:** send header `Accept: text/event-stream` on `POST /flights/rates`, or `POST /flights/rates/stream` with the same JSON body\n- Global `filters`, `sort`\n\n## Quick Start\n\n**Required:** `legs` (at least one object with `origin`, `destination`, `date`), `adults` (≥ 1), `currency`\n\n**Round-trip:** two legs (e.g. outbound then return with `direction` `OUTBOUND` / `INBOUND`). **One-way:** one leg.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["legs","adults","currency"],"properties":{"legs":{"type":"array","minItems":1,"description":"Ordered itinerary legs (provider SearchLeg). One-way: one entry. Round-trip: outbound then inbound. Multi-city / open-jaw: additional legs in travel order.","items":{"type":"object","required":["origin","destination","date"],"properties":{"origin":{"type":"string","description":"Origin airport or city IATA code for this leg","example":"JFK"},"destination":{"type":"string","description":"Destination airport or city IATA code for this leg","example":"CDG"},"date":{"type":"string","format":"date","description":"Departure date for this leg (YYYY-MM-DD)","example":"2026-07-01"},"direction":{"type":"string","enum":["OUTBOUND","INBOUND"],"description":"Leg direction (optional; defaults to OUTBOUND on the provider)","example":"OUTBOUND"},"filters":{"type":"object","description":"Optional per-leg filters overriding global `filters` for this leg","properties":{"departureTimeAfter":{"type":"string","pattern":"^([01]?[0-9]|2[0-3]):[0-5][0-9]$","description":"Departure after this local time (HH:MM, 24h)"},"departureTimeBefore":{"type":"string","pattern":"^([01]?[0-9]|2[0-3]):[0-5][0-9]$","description":"Departure before this local time (HH:MM, 24h)"},"arrivalTimeAfter":{"type":"string","pattern":"^([01]?[0-9]|2[0-3]):[0-5][0-9]$","description":"Arrival after this local time (HH:MM, 24h)"},"arrivalTimeBefore":{"type":"string","pattern":"^([01]?[0-9]|2[0-3]):[0-5][0-9]$","description":"Arrival before this local time (HH:MM, 24h)"},"excludeConnectionAirports":{"type":"array","items":{"type":"string"}},"excludeOvernight":{"type":"boolean"},"flightNumbers":{"type":"array","items":{"type":"string"}},"flightNumbersMatch":{"type":"string","enum":["any","all"]},"maxDuration":{"type":"integer","minimum":1,"description":"Max leg duration in minutes"},"maxStops":{"type":"integer","minimum":0,"maximum":2}}}}},"example":[{"origin":"JFK","destination":"CDG","date":"2026-07-01","direction":"OUTBOUND"},{"origin":"CDG","destination":"JFK","date":"2026-08-02","direction":"INBOUND"}]},"adults":{"type":"integer","minimum":1,"description":"Number of adults (12+)","example":1},"children":{"type":"integer","minimum":0,"description":"Number of children (2-11)","example":0},"infants":{"type":"integer","minimum":0,"description":"Number of infants (<2)","example":0},"childrenAges":{"type":"array","items":{"type":"integer","minimum":2,"maximum":11},"description":"Age of each child (2–11 inclusive, per IATA). Length must equal children count. Optional — omit if ages are not relevant.","example":[5,11]},"infantAges":{"type":"array","items":{"type":"integer","minimum":0,"maximum":1},"description":"Age of each infant (under 2, per IATA). Length must equal infants count. Optional — omit if ages are not relevant.","example":[1]},"cabinClass":{"type":"string","enum":["ECONOMY","PREMIUM_ECONOMY","BUSINESS","FIRST"],"description":"Cabin class (provider SearchFilters codes only). Same enum as filters.cabinClass.","example":"ECONOMY"},"currency":{"type":"string","minLength":1,"description":"ISO 4217 currency code","example":"USD"},"country":{"type":"string","description":"Optional ISO 3166-1 alpha-2 country code for point of sale","example":"US"},"filters":{"type":"object","description":"Optional filters to refine search results","example":{"maxStops":1,"maxPrice":1500,"includesCheckedBag":false,"refundableOnly":false},"properties":{"arrivalTimeBefore":{"type":"string","description":"Filter journeys arriving before this time (HH:MM, 24h)","example":"18:00","pattern":"^([01]?[0-9]|2[0-3]):[0-5][0-9]$"},"cabinClass":{"type":"string","enum":["ECONOMY","PREMIUM_ECONOMY","BUSINESS","FIRST","Economy","Business","First"],"description":"Cabin class filter (maps to provider SearchFilters.cabinClass). Overrides top-level cabinClass for this field when both are set.","example":"BUSINESS"},"cabinClassMatch":{"type":"string","enum":["exactly","at_least"],"description":"'exactly' for exact match, 'at_least' for selected cabin or better","example":"at_least"},"changeableOnly":{"type":"boolean","description":"When true, only show offers with changeable (modifiable) fares","example":false},"departureTimeBefore":{"type":"string","description":"Filter journeys departing before this time (HH:MM, 24h)","example":"14:00","pattern":"^([01]?[0-9]|2[0-3]):[0-5][0-9]$"},"excludeConnectionAirports":{"type":"array","items":{"type":"string"},"description":"Exclude layovers at these airports (e.g. IST, DOH)","example":["IST","DOH"]},"excludeOvernight":{"type":"boolean","description":"Exclude red-eye flights and overnight layovers","example":false},"flightNumbers":{"type":"array","items":{"type":"string"},"description":"Filter by flight numbers (e.g. SK500, AF123)","example":["DE2017","DE4265"]},"flightNumbersMatch":{"type":"string","enum":["any","all"],"description":"'any' = at least one match, 'all' = all specified flights","example":"any"},"includesCarryOnBag":{"type":"boolean","description":"Only show offers with carry-on included","example":false},"includesCheckedBag":{"type":"boolean","description":"Only show offers with checked bag included","example":false},"legDurations":{"type":"array","description":"Per-leg max duration constraints. Each entry limits one direction (OUTBOUND or INBOUND) independently.","example":[{"direction":"OUTBOUND","maxMinutes":600},{"direction":"INBOUND","maxMinutes":720}],"items":{"type":"object","required":["direction","maxMinutes"],"properties":{"direction":{"type":"string","enum":["OUTBOUND","INBOUND"],"description":"Which leg to constrain","example":"OUTBOUND"},"maxMinutes":{"type":"integer","minimum":1,"description":"Maximum leg duration in minutes (inclusive)","example":600}}}},"maxDuration":{"type":"integer","minimum":1,"nullable":true,"description":"Maximum total journey duration in minutes (inclusive). Journeys exceeding this duration are excluded.","example":600},"maxPrice":{"type":"number","minimum":0,"description":"Maximum total price (offer total, in search currency)","example":1500},"minPrice":{"type":"number","minimum":0,"description":"Minimum total price (offer total, in search currency)","example":200},"maxStops":{"type":"integer","nullable":true,"minimum":-1,"maximum":2,"description":"Maximum number of stops: -1 or omit = any, 0 = nonstop, 1 = 1 or fewer, 2 = 2 or fewer","example":1},"refundableOnly":{"type":"boolean","description":"When true, only show offers with refundable fares","example":false},"showCheapestOfferOnly":{"type":"boolean","description":"Return only cheapest offer per journey","example":false}}},"sort":{"type":"object","description":"Sort options for results","example":{"sortBy":"price","sortOrder":"asc"},"properties":{"sortBy":{"type":"string","enum":["price","duration","departure","arrival","stops"],"description":"Sort by price, duration, departure, arrival, or stops","example":"price"},"sortOrder":{"type":"string","enum":["asc","desc"],"description":"asc or desc","example":"asc"}}}}},"example":{"legs":[{"origin":"JFK","destination":"CDG","date":"2026-07-01","direction":"OUTBOUND"},{"origin":"CDG","destination":"JFK","date":"2026-08-02","direction":"INBOUND"}],"adults":1,"children":0,"infants":0,"currency":"USD","country":"US","sort":{"sortBy":"price","sortOrder":"asc"}}}},"description":"Flight rates search request. Itinerary is expressed only in `legs` (each leg: `origin`, `destination`, `date`; optional `direction`, `filters`). Passengers: `adults`, `children`, `infants`, optional `childrenAges` / `infantAges`. Also optional: `cabinClass`, `country` (point of sale), global `filters`, `sort`."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"journeys":{"type":"array","items":{"$ref":"#/components/schemas/FlightJourney"},"description":"Journeys returned by this provider batch, sorted by price ascending"},"sortMetadata":{"type":"object","nullable":true,"description":"Precomputed winner references for each sort criterion. Use the `offerId` to quickly look up the winning offer in `journeys[].offers[]`. Sent with every response (including SSE partial results) so the frontend can keep stable sort-tab labels without recalculating.","properties":{"best":{"$ref":"#/components/schemas/FlightSortOptionMeta","description":"Journey with the lowest blended score (price + duration + stops)"},"duration":{"$ref":"#/components/schemas/FlightSortOptionMeta","description":"Journey with the shortest total flight time"},"price":{"$ref":"#/components/schemas/FlightSortOptionMeta","description":"Cheapest journey"},"stops":{"$ref":"#/components/schemas/FlightSortOptionMeta","description":"Journey with the fewest stops"}}}}},"description":"List of search result sets, one per provider batch"}}},"example":{"data":[{"journeys":[{"journeyKey":"a3bbe883fe3a4f6b","isCheapest":true,"timestamp":"2026-03-19T12:52:59.494Z","totalDuration":{"iso8601":"PT7H45M","minutes":465},"legDurations":[{"direction":"OUTBOUND","duration":{"iso8601":"PT7H45M","minutes":465},"dayChange":1,"overnightFlight":false}],"parameters":{"adults":1,"children":0,"infants":0},"segments":[{"segmentKey":"d0a8a7dd","originCode":"JFK","originName":"John F. Kennedy International Airport","destinationCode":"CDG","destinationName":"Charles de Gaulle Airport","departureTime":"2026-07-01T16:10:00","arrivalTime":"2026-07-02T05:55:00","direction":"OUTBOUND","duration":{"iso8601":"PT7H45M","minutes":465},"flight":{"marketingNumber":"2017","operatingNumber":"2017"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}}],"offers":[{"offerId":"h6NwaWTZJDAxOWQwNjFlLWRlMjYtNzI1NC1hZDNmLTA0ZDkwZmMxMDNhZaJ0cMtAh471wo9cKaJtdctAJAAAAAAAAKNjdXKjVVNEo3VpZM0CeaJkZKoyMDI2LTA3LTAxonJkqjIwMjYtMDgtMDI=","expiration":"2026-03-19T12:52:59.494Z","pricing":{"display":{"total":753.87,"currency":"USD","base":403.63,"fees":0,"taxes":350.24,"perPassenger":{"adult":{"base":403.63,"currency":"USD","fees":0,"taxes":350.24,"total":753.87},"child":{"base":0,"currency":"USD","fees":0,"taxes":0,"total":0},"infant":{"base":0,"currency":"USD","fees":0,"taxes":0,"total":0}}},"converted":false},"fare":{"family":"Economy","mixedCabin":false,"seatsRemaining":7},"baggage":{"hasCarryOnBag":true,"hasCheckedBag":false,"included":[{"bagType":"cabin","description":"1 carry-on bag up to 8 kg","passengerType":"ADT","pieces":1,"pricing":{"display":{"amount":0,"currency":"USD"},"converted":false},"unit":"kg","weightKg":8}]},"terms":{"changeable":true,"refundable":false,"summary":[{"level":"warning","message":"Change fee applies"},{"level":"danger","message":"Non-refundable"}],"changeFee":{"pricing":{"display":{"amount":75,"currency":"USD"},"converted":false},"percent":null,"applicability":"beforeDeparture","label":"Change fee (before departure)"},"refundFee":null},"segmentFares":[{"segmentKey":"d0a8a7dd","bookingCode":"W","cabin":"Economy","fareBasisCode":"WRAQ1","fareFamily":"Economy","seatsRemaining":7}],"segmentAmenities":[{"segmentKey":"d0a8a7dd","aircraftType":"339","amenities":[{"available":true,"category":"wifi","chargeable":true,"name":"Wi-Fi","details":"Available for purchase"},{"available":true,"category":"entertainment","chargeable":false,"name":"In-seat entertainment","details":null}]}]}]}],"sortMetadata":{"best":{"journeyKey":"a3bbe883fe3a4f6b","offerId":"h6NwaWTZJDAxOWQwNjFlLWRlMjYtNzI1NC1hZDNmLTA0ZDkwZmMxMDNhZaJ0cMtAh471wo9cKaJtdctAJAAAAAAAAKNjdXKjVVNEo3VpZM0CeaJkZKoyMDI2LTA3LTAxonJkqjIwMjYtMDgtMDI=","price":753.87,"currency":"USD"},"price":{"journeyKey":"a3bbe883fe3a4f6b","offerId":"h6NwaWTZJDAxOWQwNjFlLWRlMjYtNzI1NC1hZDNmLTA0ZDkwZmMxMDNhZaJ0cMtAh471wo9cKaJtdctAJAAAAAAAAKNjdXKjVVNEo3VpZM0CeaJkZKoyMDI2LTA3LTAxonJkqjIwMjYtMDgtMDI=","price":753.87,"currency":"USD"},"duration":{"journeyKey":"a3bbe883fe3a4f6b"},"stops":{"journeyKey":"a3bbe883fe3a4f6b"}}}]}},"text/event-stream":{"schema":{"type":"string","description":"When the request includes `Accept: text/event-stream`. Server-Sent Events (SSE): each message has optional `event:` (kebab-case, e.g. `rates-chunk`, `rates-complete`, `result`, `error`, `message`) and one or more `data:` lines, terminated by a blank line. Each `data` payload is JSON with the same `data[].journeys` shape as the `application/json` 200 response (no top-level `success` or `apiMeta`)."},"example":"event: rates-chunk\ndata: {\"data\":[{\"journeys\":[{\"journeyKey\":\"a3bbe883fe3a4f6b\",\"isCheapest\":true,\"timestamp\":\"2026-03-19T12:52:59.494Z\",\"totalDuration\":{\"iso8601\":\"PT7H45M\",\"minutes\":465},\"legDurations\":[{\"direction\":\"OUTBOUND\",\"duration\":{\"iso8601\":\"PT7H45M\",\"minutes\":465},\"dayChange\":1,\"overnightFlight\":false}],\"parameters\":{\"adults\":1,\"children\":0,\"infants\":0},\"segments\":[{\"segmentKey\":\"d0a8a7dd\",\"originCode\":\"JFK\",\"originName\":\"John F. Kennedy International Airport\",\"destinationCode\":\"CDG\",\"destinationName\":\"Charles de Gaulle Airport\",\"departureTime\":\"2026-07-01T16:10:00\",\"arrivalTime\":\"2026-07-02T05:55:00\",\"direction\":\"OUTBOUND\",\"duration\":{\"iso8601\":\"PT7H45M\",\"minutes\":465},\"flight\":{\"marketingNumber\":\"2017\",\"operatingNumber\":\"2017\"},\"carrier\":{\"marketingCode\":\"DE\",\"marketingLogo\":\"https://sandbox.nuitee.flights/static/images/airlines/DE.png\",\"marketingName\":\"Condor Flugdienst\",\"operatingCode\":\"DE\",\"operatingLogo\":\"https://sandbox.nuitee.flights/static/images/airlines/DE.png\",\"operatingName\":\"Condor Flugdienst\"}}],\"offers\":[{\"offerId\":\"h6NwaWTZJDAxOWQwNjFlLWRlMjYtNzI1NC1hZDNmLTA0ZDkwZmMxMDNhZaJ0cMtAh471wo9cKaJtdctAJAAAAAAAAKNjdXKjVVNEo3VpZM0CeaJkZKoyMDI2LTA3LTAxonJkqjIwMjYtMDgtMDI=\",\"expiration\":\"2026-03-19T12:52:59.494Z\",\"pricing\":{\"display\":{\"total\":753.87,\"currency\":\"USD\",\"base\":403.63,\"fees\":0,\"taxes\":350.24,\"perPassenger\":{\"adult\":{\"base\":403.63,\"currency\":\"USD\",\"fees\":0,\"taxes\":350.24,\"total\":753.87},\"child\":{\"base\":0,\"currency\":\"USD\",\"fees\":0,\"taxes\":0,\"total\":0},\"infant\":{\"base\":0,\"currency\":\"USD\",\"fees\":0,\"taxes\":0,\"total\":0}}},\"converted\":false},\"fare\":{\"family\":\"Economy\",\"mixedCabin\":false,\"seatsRemaining\":7},\"baggage\":{\"hasCarryOnBag\":true,\"hasCheckedBag\":false,\"included\":[{\"bagType\":\"cabin\",\"description\":\"1 carry-on bag up to 8 kg\",\"passengerType\":\"ADT\",\"pieces\":1,\"pricing\":{\"display\":{\"amount\":0,\"currency\":\"USD\"},\"converted\":false},\"unit\":\"kg\",\"weightKg\":8}]},\"terms\":{\"changeable\":false,\"refundable\":false,\"summary\":[{\"level\":\"danger\",\"message\":\"Non-refundable fare\"}]},\"segmentFares\":[{\"segmentKey\":\"d0a8a7dd\",\"bookingCode\":\"W\",\"cabin\":\"Economy\",\"fareBasisCode\":\"WRAQ1\",\"fareFamily\":\"Economy\",\"seatsRemaining\":7}],\"segmentAmenities\":[{\"segmentKey\":\"d0a8a7dd\",\"aircraftType\":\"339\",\"amenities\":[{\"available\":true,\"category\":\"wifi\",\"chargeable\":true,\"name\":\"Wi-Fi\",\"details\":\"Available for purchase\"},{\"available\":true,\"category\":\"entertainment\",\"chargeable\":false,\"name\":\"In-seat entertainment\",\"details\":null}]}]}]}]}]}\n\nevent: rates-complete\ndata: {}\n"}}},"400":{"description":"Bad request — missing or invalid search parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingRequiredField":{"summary":"Missing required field","value":{"error":{"code":41002,"description":"field 'Legs' failed validation 'min'","message":"required search field is missing","key":"bodyRequest.legs"}}},"invalidParametersInfant":{"summary":"Invalid parameters: infant not allowed","value":{"error":{"code":41012,"description":"number of infants cannot exceed number of adults, each infant must be accompanied by an adult","message":"search input validation error","key":"bodyRequest.infants"}}},"invalidParametersPassenger":{"summary":"Invalid parameters: invalid passenger data","value":{"error":{"code":41006,"description":"Invalid search parameters: passenger data is invalid","message":"invalid parameters: invalid passenger data","key":"bodyRequest"}}},"validationInfant":{"summary":"Validation error: infant not allowed","value":{"error":{"code":41009,"description":"Search validation failed: infant passengers are not allowed","message":"search validation error: infant not allowed","key":"bodyRequest.infants"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"code":41004,"description":"Authentication failed","message":"unauthorized"}}},"credentialFailed":{"summary":"Credential resolution failed","value":{"error":{"code":41011,"description":"Authentication failed: credential resolution failed","message":"unauthorized: credential resolution failed"}}}}}}},"502":{"description":"Provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"providerAuthFailedConnection":{"summary":"Provider auth failed: connection","value":{"error":{"code":51001,"description":"Provider authentication failed due to connection failure","message":"provider authentication failed: connection failed","key":"bodyRequest"}}},"providerAuthFailedRoutingClosed":{"summary":"Provider auth failed: routing closed","value":{"error":{"code":51005,"description":"Provider authentication failed: routing is closed","message":"provider auth failed: routing closed","key":"bodyRequest"}}},"providerErrorRoutingClosed":{"summary":"Provider error: routing closed","value":{"error":{"code":51006,"description":"Provider returned an error: routing is closed","message":"provider error: routing closed","key":"bodyRequest"}}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"providerDisabled":{"summary":"Provider disabled","value":{"error":{"code":51003,"description":"The search provider is currently disabled","message":"search provider disabled"}}},"serviceUnavailable":{"summary":"Service unavailable","value":{"error":{"code":51004,"description":"The search service is temporarily unavailable","message":"search service unavailable"}}}}}}}}}},"/flights/rates/matrix":{"post":{"tags":["Flight Search"],"operationId":"searchFlightsMatrix","summary":"Flexible-date price matrix (one-way or round-trip)","description":"## Overview\n\nSearch the cheapest fare for each departure (and, on round-trips, return) date combination across a grid of nearby dates — `±flexDays` around the dates in your request. Accepts the same `legs`-based body as `POST /flights/rates` plus optional `flexDays` (1–3, default 3).\n\n**Supported:** one-way (1 leg) or round-trip (2 legs) only. Multi-city (3+ legs) is not supported.\n\n**Not supported:** top-level `origin`, `destination`, `departureDate`, or `returnDate` — use `legs` only.\n\n## Access\n\nRequires Flights API access and matrix enablement on your account. Matrix search is not enabled by default — contact the LiteAPI support team to request access.\n\n## When to Use\n\n- **Flexible-date calendars** — price heatmap when the traveller can shift dates\n- **Cheap-date discovery** — find the lowest fare in a ±N day window before a full `/flights/rates` search\n- **Round-trip date pairing** — compare outbound × return combinations on one grid\n- **Progressive UI** — stream cells over SSE as each underlying search completes\n\n## What You Get\n\n- **`cells`** — one entry per valid date combination, sorted by `(outboundOffset, returnOffset)`\n- **`cheapest`** — globally lowest-priced cell (null when nothing was priced)\n- **`currency`** — currency of the global cheapest cell\n- **`baseOutboundDate`** / **`baseReturnDate`** — the originally requested dates\n- **`flexDays`**, **`roundTrip`** — grid metadata\n- Per-cell **`price`**, **`currency`**, date offsets, and whether the underlying search was **`cached`** or **`success`**\n- **Margined prices** — cell `price`, `cheapest`, and `currency` include the authenticated user's rate-search margin (same as `/flights/rates`)\n\n## Key Features\n\n- Probes `±flexDays` (1–3) around requested departure and return dates\n- Each underlying date pair uses normal provider caching — a later `POST /flights/rates` for a matrix date is served from warm cache\n- **SSE:** send header `Accept: text/event-stream` for incremental events: `matrix-start` (grid skeleton), `matrix-chunk` (one priced cell), `matrix-complete` (full sorted grid + cheapest)\n- Same global `filters`, `sort`, and `options` as `/flights/rates` where applicable\n\n## Quick Start\n\n**Required:** `legs` (1 leg for one-way or 2 for round-trip, each with `origin`, `destination`, `date`), `adults` (≥ 1), `currency`\n\n**Optional:** `flexDays` (1–3, default 3), `country`, passenger counts, `filters`, `sort`\n\n**Round-trip:** two legs — outbound then return with optional `direction` `OUTBOUND` / `INBOUND`. **One-way:** one leg.\n\nAfter choosing a date pair from the matrix, call `POST /flights/rates` with `legs` set to those dates for full offer details.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["legs","adults","currency"],"properties":{"legs":{"type":"array","minItems":1,"maxItems":2,"description":"One leg (one-way) or two legs (round-trip). Multi-city is not supported.","items":{"type":"object","required":["origin","destination","date"],"properties":{"origin":{"type":"string","description":"Origin airport or city IATA code for this leg.","example":"LON"},"destination":{"type":"string","description":"Destination airport or city IATA code for this leg.","example":"PAR"},"date":{"type":"string","format":"date","description":"Departure date for this leg (YYYY-MM-DD).","example":"2026-08-26"},"direction":{"type":"string","enum":["OUTBOUND","INBOUND"],"description":"Leg direction (optional; defaults to OUTBOUND on the provider)."}}}},"adults":{"type":"integer","minimum":1,"description":"Number of adult passengers (≥ 1).","example":1},"children":{"type":"integer","minimum":0,"description":"Number of child passengers (ages 2-11).","example":0},"infants":{"type":"integer","minimum":0,"description":"Number of infant passengers (under 2).","example":0},"currency":{"type":"string","description":"ISO 4217 currency for point of sale and displayed prices.","example":"EUR"},"country":{"type":"string","description":"ISO country code for point of sale","example":"us"},"flexDays":{"type":"integer","minimum":1,"maximum":3,"default":3,"description":"Days before/after requested dates to probe"}}}}}},"responses":{"200":{"description":"Price matrix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlightMatrixResponse"},"example":{"data":[{"baseOutboundDate":"2026-08-26","cells":[{"outboundDate":"2026-08-23","outboundOffset":-3,"price":491.81,"currency":"EUR","success":true,"cached":true},{"outboundDate":"2026-08-24","outboundOffset":-2,"price":804.98,"currency":"EUR","success":true,"cached":true},{"outboundDate":"2026-08-25","outboundOffset":-1,"price":804.98,"currency":"EUR","success":true,"cached":true},{"outboundDate":"2026-08-26","outboundOffset":0,"price":592.9,"currency":"EUR","success":true,"cached":true},{"outboundDate":"2026-08-27","outboundOffset":1,"price":926.2,"currency":"EUR","success":true,"cached":true},{"outboundDate":"2026-08-28","outboundOffset":2,"price":926.2,"currency":"EUR","success":true,"cached":true},{"outboundDate":"2026-08-29","outboundOffset":3,"price":542.29,"currency":"EUR","success":true,"cached":true}],"cheapest":{"outboundDate":"2026-08-23","outboundOffset":-3,"price":491.81,"currency":"EUR","success":true,"cached":true},"currency":"EUR","flexDays":3,"roundTrip":false}]}},"text/event-stream":{"schema":{"type":"string","description":"When the request includes `Accept: text/event-stream`. Server-Sent Events (SSE): each message has an `event:` line (kebab-case: `matrix-start`, `matrix-chunk`, `matrix-complete`) and one or more `data:` lines, terminated by a blank line. All events use the same `{\"data\":[...]}` envelope as the JSON 200 response. `matrix-start` carries the grid skeleton (unpriced cells + `totalCells`). Each `matrix-chunk` carries one priced cell in the same `data[]` shape as the `application/json` 200 response. `matrix-complete` carries the full sorted grid and `cheapest` (parallel to `rates-chunk` / `rates-complete` on `POST /flights/rates`)."},"example":"event: matrix-start\ndata: {\"data\":[{\"baseOutboundDate\":\"2026-08-26\",\"baseReturnDate\":null,\"cells\":[{\"outboundDate\":\"2026-08-23\",\"returnDate\":null,\"outboundOffset\":-3,\"returnOffset\":null,\"success\":false,\"price\":null,\"currency\":null,\"cached\":false,\"error\":null},{\"outboundDate\":\"2026-08-24\",\"returnDate\":null,\"outboundOffset\":-2,\"returnOffset\":null,\"success\":false,\"price\":null,\"currency\":null,\"cached\":false,\"error\":null},{\"outboundDate\":\"2026-08-25\",\"returnDate\":null,\"outboundOffset\":-1,\"returnOffset\":null,\"success\":false,\"price\":null,\"currency\":null,\"cached\":false,\"error\":null},{\"outboundDate\":\"2026-08-26\",\"returnDate\":null,\"outboundOffset\":0,\"returnOffset\":null,\"success\":false,\"price\":null,\"currency\":null,\"cached\":false,\"error\":null},{\"outboundDate\":\"2026-08-27\",\"returnDate\":null,\"outboundOffset\":1,\"returnOffset\":null,\"success\":false,\"price\":null,\"currency\":null,\"cached\":false,\"error\":null},{\"outboundDate\":\"2026-08-28\",\"returnDate\":null,\"outboundOffset\":2,\"returnOffset\":null,\"success\":false,\"price\":null,\"currency\":null,\"cached\":false,\"error\":null},{\"outboundDate\":\"2026-08-29\",\"returnDate\":null,\"outboundOffset\":3,\"returnOffset\":null,\"success\":false,\"price\":null,\"currency\":null,\"cached\":false,\"error\":null}],\"flexDays\":3,\"roundTrip\":false,\"totalCells\":7}]}\n\nevent: matrix-chunk\ndata: {\"data\":[{\"baseOutboundDate\":\"\",\"cells\":[{\"outboundDate\":\"2026-08-24\",\"outboundOffset\":-2,\"price\":805.08,\"currency\":\"EUR\",\"success\":true,\"cached\":true}],\"flexDays\":0,\"roundTrip\":false}]}\n\nevent: matrix-chunk\ndata: {\"data\":[{\"baseOutboundDate\":\"\",\"cells\":[{\"outboundDate\":\"2026-08-25\",\"outboundOffset\":-1,\"price\":805.08,\"currency\":\"EUR\",\"success\":true,\"cached\":true}],\"flexDays\":0,\"roundTrip\":false}]}\n\nevent: matrix-chunk\ndata: {\"data\":[{\"baseOutboundDate\":\"\",\"cells\":[{\"outboundDate\":\"2026-08-23\",\"outboundOffset\":-3,\"price\":491.81,\"currency\":\"EUR\",\"success\":true,\"cached\":true}],\"flexDays\":0,\"roundTrip\":false}]}\n\nevent: matrix-chunk\ndata: {\"data\":[{\"baseOutboundDate\":\"\",\"cells\":[{\"outboundDate\":\"2026-08-26\",\"outboundOffset\":0,\"price\":592.9,\"currency\":\"EUR\",\"success\":true,\"cached\":true}],\"flexDays\":0,\"roundTrip\":false}]}\n\nevent: matrix-chunk\ndata: {\"data\":[{\"baseOutboundDate\":\"\",\"cells\":[{\"outboundDate\":\"2026-08-28\",\"outboundOffset\":2,\"price\":926.2,\"currency\":\"EUR\",\"success\":true,\"cached\":true}],\"flexDays\":0,\"roundTrip\":false}]}\n\nevent: matrix-chunk\ndata: {\"data\":[{\"baseOutboundDate\":\"\",\"cells\":[{\"outboundDate\":\"2026-08-27\",\"outboundOffset\":1,\"price\":926.2,\"currency\":\"EUR\",\"success\":true,\"cached\":true}],\"flexDays\":0,\"roundTrip\":false}]}\n\nevent: matrix-chunk\ndata: {\"data\":[{\"baseOutboundDate\":\"\",\"cells\":[{\"outboundDate\":\"2026-08-29\",\"outboundOffset\":3,\"price\":542.29,\"currency\":\"EUR\",\"success\":true,\"cached\":true}],\"flexDays\":0,\"roundTrip\":false}]}\n\nevent: matrix-complete\ndata: {\"data\":[{\"baseOutboundDate\":\"2026-08-26\",\"cells\":[{\"outboundDate\":\"2026-08-23\",\"outboundOffset\":-3,\"price\":491.81,\"currency\":\"EUR\",\"success\":true,\"cached\":true},{\"outboundDate\":\"2026-08-24\",\"outboundOffset\":-2,\"price\":805.08,\"currency\":\"EUR\",\"success\":true,\"cached\":true},{\"outboundDate\":\"2026-08-25\",\"outboundOffset\":-1,\"price\":805.08,\"currency\":\"EUR\",\"success\":true,\"cached\":true},{\"outboundDate\":\"2026-08-26\",\"outboundOffset\":0,\"price\":592.9,\"currency\":\"EUR\",\"success\":true,\"cached\":true},{\"outboundDate\":\"2026-08-27\",\"outboundOffset\":1,\"price\":926.2,\"currency\":\"EUR\",\"success\":true,\"cached\":true},{\"outboundDate\":\"2026-08-28\",\"outboundOffset\":2,\"price\":926.2,\"currency\":\"EUR\",\"success\":true,\"cached\":true},{\"outboundDate\":\"2026-08-29\",\"outboundOffset\":3,\"price\":542.29,\"currency\":\"EUR\",\"success\":true,\"cached\":true}],\"cheapest\":{\"outboundDate\":\"2026-08-23\",\"outboundOffset\":-3,\"price\":491.81,\"currency\":\"EUR\",\"success\":true,\"cached\":true},\"currency\":\"EUR\",\"flexDays\":3,\"roundTrip\":false}]}\n"}}},"400":{"description":"Bad request — missing or invalid matrix search parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingRequiredField":{"summary":"Missing required field","value":{"error":{"code":41002,"description":"field 'Legs' failed validation 'min'","message":"required search field is missing","key":"bodyRequest.legs"}}},"invalidParametersInfant":{"summary":"Invalid parameters: infant not allowed","value":{"error":{"code":41012,"description":"number of infants cannot exceed number of adults, each infant must be accompanied by an adult","message":"search input validation error","key":"bodyRequest.infants"}}},"invalidLegCount":{"summary":"Matrix supports one-way or round-trip only","value":{"error":{"code":41012,"description":"matrix search supports one-way (1 leg) or round-trip (2 legs) only","message":"search input validation error","key":"bodyRequest.legs"}}},"invalidFlexDays":{"summary":"Invalid flexDays value","value":{"error":{"code":41012,"description":"must be between 1 and 3","message":"search input validation error","key":"bodyRequest.flexDays"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"code":41004,"description":"Authentication failed","message":"unauthorized"}}},"credentialFailed":{"summary":"Credential resolution failed","value":{"error":{"code":41011,"description":"Authentication failed: credential resolution failed","message":"unauthorized: credential resolution failed"}}}}}}},"403":{"description":"Forbidden — matrix access not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":40301,"description":"user does not have enough permissions to perform this action","message":"Flights matrix API access is not enabled for this account. Please contact support to get access"}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":51099,"description":"Failed to search flight matrix","message":"unable to process search request"}}}}}}}},"/flights/verify":{"post":{"tags":["Flight Search"],"summary":"Verify flight offer","description":"## Overview\n\nConfirm a flight offer is still available and retrieve the latest pricing before proceeding to booking. Always verify before prebooking to avoid price discrepancies.\n\n## When to Use\n\n- **Pre-booking validation** - Confirm offer availability after user selects a flight\n- **Price confirmation** - Show users the guaranteed price before they enter payment details\n- **Fare rule retrieval** - Get the latest cancellation and change policies\n\n## What You Get\n\n- **Verified pricing** with up-to-date fare breakdown\n- **`changes`** (when present) — cabin/fare flags, human-readable `messages`, and **`pricing`** (`old` / `new` full OfferPricing) instead of deprecated scalar currency/prices\n- **Journey `pricing`** — `original` (provider/PCC) and `display` (customer) price breakdown per provider FlattenedJourney\n- **Fare family details** including name and included amenities\n- **Baggage policy** for each passenger type and segment\n- **Booking terms** including cancellation and change fee rules\n\n## Key Features\n\n- **Real-time price check**: Confirms current availability and price with the provider\n- **Updated baggage info**: Returns the latest baggage allowances at time of verification\n- **Fare rules**: Includes cancellation and change fee policies before commitment\n\n## Quick Start\n\nProvide the `offerId` from `/flights/rates` search results. Use the verified offer data to populate a booking summary page before proceeding to `/flights/prebooks`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offerId"],"properties":{"offerId":{"type":"string","description":"The offerId from the search results"}}},"example":{"offerId":"h6NwaWTZJDAxOWQwNjIwLWQzMDItNzBiYS04OGUxLTdlMTdkMzYyZDQ0MKJ0cMtAkdkUeuFHrqJtdcsAAAAAAAAAAKNjdXKjVVNEo3VpZM0CeaJkZKoyMDI2LTA3LTAxonJkqjIwMjYtMDgtMDI="}}},"description":"The offerId to verify before booking"},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"journey":{"$ref":"#/components/schemas/FlightVerifyJourney","description":"Verified journey with updated pricing, baggage, and terms"},"changes":{"$ref":"#/components/schemas/FlightVerifyChanges","description":"Changes detected since search (price, cabin, fare); omitted when the provider sends no changes block","nullable":true}}},"description":"Verified journey result"}}},"example":{"data":[{"journey":{"journeyKey":"26b2fa3085dc22b2","expiration":"2026-03-19T13:15:09.485Z","timestamp":"2026-03-19T12:45:07.715Z","provider":{"code":"SABRE","logo":"https://production.nuitee.flights/static/providers/sabre.svg"},"pricing":{"display":{"total":1423.42,"currency":"USD","base":1127.92,"fees":0,"taxes":295.5,"perPassenger":{"adult":{"base":1127.92,"currency":"USD","fees":0,"taxes":295.5,"total":1423.42},"child":{"base":0,"currency":"USD","fees":0,"taxes":0,"total":0},"infant":{"base":0,"currency":"USD","fees":0,"taxes":0,"total":0}}},"converted":true},"baggage":{"hasCarryOnBag":true,"hasCheckedBag":true,"included":[{"bagType":"checked","description":"","passengerType":"ADT","pieces":1,"pricing":{"display":{"amount":0,"currency":"EUR"},"converted":false},"weightKg":23},{"bagType":"cabin","description":"Cabin bag","passengerType":"ADT","pieces":1,"pricing":{"display":{"amount":0,"currency":"EUR"},"converted":false},"unit":"kg","weightKg":8}]},"fare":{"family":"Economy","mixedCabin":false,"seatsRemaining":9},"passengers":{"adults":1,"children":0,"infants":0},"segments":[{"segmentKey":"096fada4","originCode":"JFK","originName":"John F. Kennedy International Airport","destinationCode":"FRA","destinationName":"Frankfurt Main Airport","departureTime":"2026-07-01T16:25:00","arrivalTime":"2026-07-02T06:10:00","direction":"OUTBOUND","duration":{"iso8601":"PT7H45M","minutes":465},"flight":{"marketingNumber":"2017","operatingNumber":"2017"},"carrier":{"marketingCode":"DE","marketingLogo":"https://production.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://production.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"8528a309","originCode":"FRA","originName":"Frankfurt Main Airport","destinationCode":"CDG","destinationName":"Charles de Gaulle International Airport","departureTime":"2026-07-02T08:55:00","arrivalTime":"2026-07-02T10:15:00","direction":"OUTBOUND","duration":{"iso8601":"PT1H20M","minutes":80},"flight":{"marketingNumber":"4265","operatingNumber":"4265"},"carrier":{"marketingCode":"DE","marketingLogo":"https://production.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://production.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"f15d5c4e","originCode":"CDG","originName":"Charles de Gaulle International Airport","destinationCode":"FRA","destinationName":"Frankfurt Main Airport","departureTime":"2026-08-02T08:25:00","arrivalTime":"2026-08-02T09:55:00","direction":"INBOUND","duration":{"iso8601":"PT1H30M","minutes":90},"flight":{"marketingNumber":"4292","operatingNumber":"4292"},"carrier":{"marketingCode":"DE","marketingLogo":"https://production.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://production.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"af5b7649","originCode":"FRA","originName":"Frankfurt Main Airport","destinationCode":"JFK","destinationName":"John F. Kennedy International Airport","departureTime":"2026-08-02T11:40:00","arrivalTime":"2026-08-02T14:25:00","direction":"INBOUND","duration":{"iso8601":"PT8H45M","minutes":525},"flight":{"marketingNumber":"2016","operatingNumber":"2016"},"carrier":{"marketingCode":"DE","marketingLogo":"https://production.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://production.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}}],"segmentFares":[{"segmentKey":"096fada4","bookingCode":"U","cabin":"Economy","fareBasisCode":"URA1","fareFamily":"Economy","seatsRemaining":9},{"segmentKey":"8528a309","bookingCode":"W","cabin":"Economy","fareBasisCode":"URA1","fareFamily":"Economy","seatsRemaining":9},{"segmentKey":"f15d5c4e","bookingCode":"W","cabin":"Economy","fareBasisCode":"KRA1","fareFamily":"Economy","seatsRemaining":9},{"segmentKey":"af5b7649","bookingCode":"K","cabin":"Economy","fareBasisCode":"KRA1","fareFamily":"Economy","seatsRemaining":9}],"terms":{"changeable":false,"refundable":false,"summary":[{"level":"danger","message":"Non-refundable"},{"level":"danger","message":"Changes not allowed"},{"level":"info","message":"Book by: 2026-03-22 12:44"}],"changeFee":null,"refundFee":{"pricing":{"display":{"amount":200,"currency":"USD"},"converted":false},"percent":100,"applicability":"noShow","label":"No-show fee"}}}}]}}}},"400":{"description":"Bad request — missing or invalid verify parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingRequiredField":{"summary":"Missing required field","value":{"error":{"code":42001,"description":"invalid offerId","message":"required verify field is missing","key":"bodyRequest.offerId"}}},"invalidParametersInvalidId":{"summary":"Invalid parameters: invalid ID format","value":{"error":{"code":42013,"description":"The offer ID provided is not a valid UUIDv7.","message":"validation error: invalid ID format","key":"bodyRequest"}}},"validationSessionExpired":{"summary":"Validation error: session expired","value":{"error":{"code":42015,"description":"Verify validation failed: the session has expired","message":"verify validation error: session expired","key":"bodyRequest.offerId"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"code":42003,"description":"Authentication failed","message":"unauthorized"}}},"credentialFailed":{"summary":"Credential resolution failed","value":{"error":{"code":42016,"description":"Authentication failed: credential resolution failed","message":"unauthorized: credential resolution failed"}}}}}}},"404":{"description":"Offer expired, not found, or session expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notFoundOfferExpired":{"summary":"Not found: offer expired","value":{"error":{"code":42004,"description":"The offer has expired. Please search for new flights","message":"offer expired","key":"bodyRequest.offerId"}}},"expiredOfferExpired":{"summary":"Expired: offer expired","value":{"error":{"code":42017,"description":"The offer has expired","message":"expired: offer expired","key":"bodyRequest.offerId"}}},"expiredOfferNotFound":{"summary":"Expired: offer not found","value":{"error":{"code":42018,"description":"Expired: the offer was not found","message":"expired: offer not found","key":"bodyRequest.offerId"}}},"expiredSessionExpired":{"summary":"Expired: session expired","value":{"error":{"code":42019,"description":"Expired: the session has expired","message":"expired: session expired","key":"bodyRequest.offerId"}}}}}}},"502":{"description":"Provider error during verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"providerAuthFailedFlightInfoChanged":{"summary":"Flight info changed","value":{"error":{"code":52001,"description":"Provider auth failed: flight information has changed","message":"provider auth failed: flight info changed","key":"bodyRequest"}}},"providerAuthFailedOfferExpired":{"summary":"Provider auth failed: offer expired","value":{"error":{"code":52016,"description":"Provider auth failed: the offer has expired","message":"provider auth failed: offer expired","key":"bodyRequest"}}},"providerErrorOfferNotFound":{"summary":"Provider error: offer not found","value":{"error":{"code":52019,"description":"Provider error: the offer was not found","message":"provider error: offer not found","key":"bodyRequest"}}},"providerErrorConnection":{"summary":"Provider connection failed","value":{"error":{"code":52011,"description":"Provider error: connection to provider failed","message":"provider error: connection failed","key":"bodyRequest"}}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"cacheUnavailable":{"summary":"Cache unavailable","value":{"error":{"code":52013,"description":"The verify cache is unavailable","message":"verify cache unavailable"}}},"providerDisabled":{"summary":"Provider disabled","value":{"error":{"code":52014,"description":"The verify provider is disabled","message":"verify provider disabled"}}},"serviceUnavailable":{"summary":"Service unavailable","value":{"error":{"code":52015,"description":"The verify service is temporarily unavailable","message":"verify service unavailable"}}}}}}}}}},"/flights/prebooks/{prebookId}/services":{"post":{"tags":["Flight Bookings"],"summary":"1.2 Attach services to prebook (Optional)","description":"## Overview\n\nAdd ancillary services such as seat selection or extra baggage to an existing prebook before confirming the final booking.\n\n## When to Use\n\n- **Seat selection** - Allow users to choose specific seats after prebook\n- **Extra baggage** - Let users add additional luggage allowance\n- **Price update** - Required when services change the total booking cost\n- **Voucher discount** - Optional `voucherCode` when attaching services changes the total and you need the discount reflected on the new payment intent\n\n## What You Get\n\n- **Updated prebook** with the selected services attached\n- **New payment intent** (`transactionId`, `secretKey`) reflecting the updated total price (after any voucher discount)\n- **Same response format** as `POST /flights/prebooks` for easy integration\n\n## Key Features\n\n- **Seat selection**: Assign specific seats to each passenger and segment\n- **Extra baggage**: Add checked baggage or overweight allowances\n- **Updated payment**: Creates a new Stripe payment intent when the prebook used Stripe (`usePaymentSdk: true`). When the prebook used credit line only (`usePaymentSdk: false`), no new intent is returned\n- **Voucher recalculation**: When a voucher applies, the discount is recomputed against the updated total (journey + ancillaries); invalid or expired vouchers return `400` (same as prebook)\n- **Modifies in place**: Updates the existing prebook record in the database\n\n## Quick Start\n\nProvide the `prebookId` in the URL path and `selectedServices` in the request body. Optionally pass `voucherCode` to apply a discount. Use the **new** `transactionId` from this response (not the original prebook `transactionId`) when confirming payment with Stripe and when calling `POST /flights/bookings`.","parameters":[{"name":"prebookId","in":"path","required":true,"schema":{"type":"string"},"description":"The prebook ID (must have provider_booking_id from initial prebook)","example":"019d0674-834d-7db7-9c8b-93fe8e46e7b8"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["selectedServices"],"properties":{"selectedServices":{"type":"array","items":{"$ref":"#/components/schemas/SelectedService"},"description":"Services to attach (from servicesAttachable.groups in prebook response)"},"voucherCode":{"type":"string","description":"An optional voucher code to apply discounts to the booking. The vouchers API allows creation of these discounts"}}},"example":{"selectedServices":[{"passengerIndex":0,"serviceId":"g6Rwc2lk2SQwMTlkMDY3NC1hMzQzLTc0OGEtYmYyYS1jMDk4ZmNjMTk2ZGGhcMtAfB6PXCj1w6Fjo1VTRA==","quantity":1}],"voucherCode":"createvoucher83"}}},"description":"Selected ancillary services to attach to the prebook"},"responses":{"200":{"description":"Services attached successfully; returns updated prebook data with new price and transactionId","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"prebookId":{"type":"string","description":"Unique prebook identifier"},"booking":{"$ref":"#/components/schemas/FlightBooking","description":"Updated booking record after attaching services"},"servicesAttachable":{"type":"object","properties":{"expiresAt":{"type":"string","description":"Expiry time for attaching services (ISO 8601)"},"groups":{"type":"array","description":"Remaining available ancillary services after attachment","items":{"type":"object","properties":{"available":{"type":"boolean","description":"Whether any services in this group are currently available"},"category":{"type":"string","description":"Service category (e.g. seat, baggage)"},"label":{"type":"string","description":"Human-readable group label"},"services":{"type":"array","items":{"type":"object","properties":{"serviceId":{"type":"string","description":"Unique service identifier — use this in selectedServices when attaching"},"name":{"type":"string","description":"Human-readable service name (e.g. Seat 7A)"},"category":{"type":"string","description":"Service category (e.g. seat, baggage)"},"passengerType":{"type":"string","description":"Applicable passenger type (ALL, ADT, CHD, INF)"},"segmentKey":{"type":"string","description":"The segment this service applies to"},"pricing":{"$ref":"#/components/schemas/FlightItemPricing","description":"Price of this service (amount 0 means included)"},"metadata":{"type":"object","description":"Category-specific metadata. Contains exactly one of `seat` (when category is `seat`) or `baggage` (when category is `baggage`).","properties":{"seat":{"type":"object","description":"Seat details — present only when the service category is `seat`","properties":{"available":{"type":"boolean","description":"Whether this seat is currently available for selection"},"position":{"type":"string","description":"Physical position in the row (e.g. window, middle, aisle)"},"seatColumn":{"type":"string","description":"Column letter (e.g. A, B, C)"},"seatNumber":{"type":"string","description":"Full seat label (e.g. 1A)"},"seatRow":{"type":"integer","description":"Row number"},"seatType":{"type":"string","description":"Seat class/type (e.g. standard, extra_legroom, exit_row)"}}},"baggage":{"type":"object","description":"Baggage details — present only when the service category is `baggage`","properties":{"bagType":{"type":"string","description":"Type of bag (e.g. checked, cabin)"},"pieces":{"type":"integer","description":"Number of bag pieces included"},"weightKg":{"type":"number","description":"Weight allowance in kilograms"}}}}}}},"description":"Available services in this group"}}}}},"description":"Remaining ancillary services available to attach"},"price":{"type":"number","description":"Updated total price including attached services"},"currency":{"type":"string","description":"ISO 4217 currency code for the updated price"},"transactionId":{"type":"string","description":"New Stripe transaction ID reflecting the updated price — use this (not the prebook transactionId) when calling /bookings"},"secretKey":{"type":"string","description":"New Stripe payment intent secret key for SDK confirmation"},"voucherCode":{"type":"string","description":"Represents the unique code used to redeem a voucher during the transaction."},"voucherTotalAmount":{"type":"number","description":"Specifies the total monetary value or discount amount provided by the voucher, in `currency`."},"sellingPriceToUser":{"type":"number","description":"Amount the customer pays after the voucher discount (`price` minus `voucherTotalAmount`)."}}},"description":"Updated prebook result after attaching services"}}},"example":{"data":[{"prebookId":"019d0674-834d-7db7-9c8b-93fe8e46e7b8","booking":{"timestamp":"2026-03-19T14:16:40Z","journey":{"journeyKey":"30073d47d441f174","segments":[{"segmentKey":"b4cd7e77","originCode":"JFK","originName":"John F. Kennedy International Airport","destinationCode":"FRA","destinationName":"Frankfurt Main Airport","departureTime":"2026-07-02T16:10:00","arrivalTime":"2026-07-03T05:55:00","direction":"OUTBOUND","duration":{"iso8601":"PT7H45M","minutes":465},"flight":{"marketingNumber":"2017","operatingNumber":"2017"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"35125125","originCode":"FRA","originName":"Frankfurt Main Airport","destinationCode":"CDG","destinationName":"Charles de Gaulle International Airport","departureTime":"2026-07-03T08:30:00","arrivalTime":"2026-07-03T09:50:00","direction":"OUTBOUND","duration":{"iso8601":"PT1H20M","minutes":80},"flight":{"marketingNumber":"4265","operatingNumber":"4265"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"f15d5c4e","originCode":"CDG","originName":"Charles de Gaulle International Airport","destinationCode":"FRA","destinationName":"Frankfurt Main Airport","departureTime":"2026-08-02T08:25:00","arrivalTime":"2026-08-02T09:55:00","direction":"INBOUND","duration":{"iso8601":"PT1H30M","minutes":90},"flight":{"marketingNumber":"4292","operatingNumber":"4292"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"7eccefc8","originCode":"FRA","originName":"Frankfurt Main Airport","destinationCode":"JFK","destinationName":"John F. Kennedy International Airport","departureTime":"2026-08-02T11:25:00","arrivalTime":"2026-08-02T14:10:00","direction":"INBOUND","duration":{"iso8601":"PT8H45M","minutes":525},"flight":{"marketingNumber":"2016","operatingNumber":"2016"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}}],"pricing":{"display":{"total":740.27,"currency":"USD","base":421.87,"fees":0,"taxes":318.4,"perPassenger":{"adult":{"base":421.87,"currency":"USD","fees":0,"taxes":318.4,"total":740.27},"child":{"base":0,"currency":"USD","fees":0,"taxes":0,"total":0},"infant":{"base":0,"currency":"USD","fees":0,"taxes":0,"total":0}}},"converted":true},"terms":{"changeable":true,"refundable":false,"summary":[{"level":"warning","message":"Change fee applies"},{"level":"danger","message":"Non-refundable"}],"changeFee":{"pricing":{"display":{"amount":75,"currency":"USD"},"converted":false},"percent":null,"applicability":"beforeDeparture","label":"Change fee (before departure)"},"refundFee":null}},"passengers":[{"firstName":"JOHN","lastName":"Doe","middleName":"Joshua","birthday":"1996-04-28","gender":"M","nationality":"TN","documentType":"passport","documentNumber":"123456789","documentIssueCountry":"US","documentExpiry":"2030-04-28"}],"order":{"reference":{"orderId":"OQTYXX","airlineBookings":[{"airlineCode":"DE","airlineName":"Condor Flugdienst","airlinePnr":"DCDE"}]}},"contact":{"firstName":"JOHN","email":"j.doe@example.com"},"selectedServices":[{"passengerIndex":0,"serviceId":"g6Rwc2lk2SQwMTlkMDY3NC1hMzQzLTc0OGEtYmYyYS1jMDk4ZmNjMTk2ZGGhcMtAfB6PXCj1w6Fjo1VTRA==","quantity":1}]},"price":1149.28,"currency":"USD","transactionId":"tr_cts_t0LaZePPxdCM_Kyskafml","secretKey":"pi_3TChUfA4FXPoRk9Y0tQbfO9i_secret_fwHM73I5dHKOmcWJ3K468UX3g","voucherCode":"createvoucher83","voucherTotalAmount":20,"sellingPriceToUser":1129.28,"servicesAttachable":{"expiresAt":"2026-03-19T14:31:42.493Z","groups":[{"available":true,"category":"seat","label":"Seat Selection","services":[{"serviceId":"g6Rwc2lk2SQwMTlkMDY3NC1hYWY1LTczMjktODhiNy03OTdlNTc5YWJmZjWhcMtANdR64UeuFKFjo1VTRA==","name":"Seat 7A","category":"seat","passengerType":"ALL","segmentKey":"35125125","pricing":{"display":{"amount":21.83,"currency":"USD"},"converted":true},"metadata":{"seat":{"available":true,"position":"window","seatColumn":"A","seatNumber":"7A","seatRow":7,"seatType":"extra_legroom"}}},{"serviceId":"g6Rwc2lk2SQwMTlkMDY3NC1hYWY1LTczMjktODhiNy03OTdmZmYzMTczMGWhcMtANdR64UeuFKFjo1VTRA==","name":"Seat 7B","category":"seat","passengerType":"ALL","segmentKey":"35125125","pricing":{"display":{"amount":21.83,"currency":"USD"},"converted":true},"metadata":{"seat":{"available":true,"position":"middle","seatColumn":"B","seatNumber":"7B","seatRow":7,"seatType":"standard"}}}]},{"available":true,"category":"baggage","label":"Extra Baggage","services":[{"serviceId":"g6Rwc2lk2SQwMTlkMDY3NC1iYWcxLTczMjktODhiNy04OTdlNTc5YWJmZjWhcMtANdR64UeuFKFjo1VTRA==","name":"Standard Check In Baggage 10kg","category":"baggage","passengerType":"ALL","segmentKey":"35125125","pricing":{"display":{"amount":13.62,"currency":"USD"},"converted":true},"metadata":{"baggage":{"bagType":"checked","pieces":1,"weightKg":10}}}]}]}}]}}}},"400":{"description":"Bad request — missing or invalid service parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingFieldAncillary":{"summary":"Missing field: ancillary not found","value":{"error":{"code":44001,"description":"Required field is missing: ancillary not found","message":"required field missing: ancillary not found","key":"bodyRequest.selectedServices"}}},"missingFieldInvalidId":{"summary":"Missing field: invalid ID format","value":{"error":{"code":44008,"description":"Required field is missing: invalid ID format","message":"missing required field: invalid ID format","key":"bodyRequest"}}},"validationSeatUnavailable":{"summary":"Validation error: seat unavailable","value":{"error":{"code":44012,"description":"Validation failed: the requested seat is unavailable","message":"validation error: seat unavailable","key":"bodyRequest.selectedServices"}}},"validationSessionExpired":{"summary":"Validation error: session expired","value":{"error":{"code":44013,"description":"Validation failed: the session has expired","message":"validation error: session expired","key":"bodyRequest"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"code":44003,"description":"Authentication failed","message":"unauthorized"}}},"credentialFailed":{"summary":"Credential resolution failed","value":{"error":{"code":44014,"description":"Authentication failed: credential resolution failed","message":"unauthorized: credential resolution failed"}}}}}}},"404":{"description":"Prebook or booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"bookingNotFound":{"summary":"Booking not found","value":{"error":{"code":44004,"description":"The booking was not found","message":"booking not found","key":"pathParam.prebookId"}}},"pnrNotFound":{"summary":"PNR not found","value":{"error":{"code":44005,"description":"The PNR was not found","message":"PNR not found","key":"pathParam.bookingId"}}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidStatusTransition":{"summary":"Invalid status transition","value":{"error":{"code":44006,"description":"Services can only be attached before the booking is in status CONFIRMED","message":"booking status does not allow service attachment","key":"bodyRequest.prebookId"}}},"serviceConflict":{"summary":"Service conflict","value":{"error":{"code":44007,"description":"Service conflict during attachment","message":"conflict: service conflict","key":"bodyRequest.prebookId"}}}}}}},"502":{"description":"Provider error during service attachment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"providerAuthFailedCredential":{"summary":"Provider auth failed: credential resolution","value":{"error":{"code":54005,"description":"Provider auth failed: credential resolution failed","message":"provider auth failed: credential resolution failed","key":"bodyRequest"}}},"providerAuthFailedGds":{"summary":"Provider auth failed: GDS rejection","value":{"error":{"code":54006,"description":"Provider auth failed: rejected by GDS","message":"provider auth failed: GDS rejection","key":"bodyRequest"}}},"providerDisabledNotSupported":{"summary":"Provider disabled: services not supported","value":{"error":{"code":54016,"description":"Provider disabled: services are not supported","message":"provider disabled: services not supported","key":"bodyRequest"}}},"gdsRejection":{"summary":"Provider error: GDS rejection","value":{"error":{"code":54001,"description":"Provider error: rejected by GDS","message":"provider error: GDS rejection"}}},"seatUnavailable":{"summary":"Seat unavailable","value":{"error":{"code":54003,"description":"Provider error: the requested seat is unavailable","message":"provider error: seat unavailable"}}}}}}}}}},"/flights/bookings/{bookingId}":{"get":{"tags":["Flight Bookings"],"summary":"Get booking details","description":"## Overview\n\nRetrieve complete details of a confirmed flight booking using its unique booking ID.\n\n## When to Use\n\n- **Booking confirmation page** - Display full itinerary after booking completes\n- **Booking management** - Retrieve details for an existing reservation\n- **Itinerary display** - Show passengers, segments, and confirmation numbers\n- **Status checks** - Verify booking status for a given booking ID\n\n## What You Get\n\n- **Complete itinerary** with all flight segments and connection details\n- **Passenger manifest** with names, documents, and seat assignments\n- **Booking status** and provider confirmation reference\n- **Pricing breakdown** including taxes and fees paid\n\n## Key Features\n\n- **Full booking record**: Returns all data associated with the confirmed booking\n- **Provider reference**: Includes the provider-side booking confirmation number\n- **Passenger details**: Complete passenger information for all travelers\n\n## Quick Start\n\nProvide the `bookingId` (returned from `POST /flights/bookings`) in the URL path. Returns the complete booking record.","parameters":[{"name":"bookingId","in":"path","required":true,"schema":{"type":"string"},"description":"The unique booking identifier","example":"1297abe4-57c5-4605-b8e7-5caad983c4a7"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/FlightBooking","description":"Full booking record including status, journey, passengers, order reference, and payment details"}}},"description":"Booking result array (always one item)"}}},"example":{"data":[{"booking":{"bookingId":"1297abe4-57c5-4605-b8e7-5caad983c4a7","status":"CONFIRMED","timestamp":"2026-02-09T14:20:32.416Z","journey":{"journeyKey":"a3bbe883fe3a4f6b","segments":[{"arrivalTime":"2026-04-10T18:40:00","carrier":{"marketingCode":"B6","marketingLogo":"/static/images/airlines/B6.png","marketingName":"JetBlue Airways","operatingCode":"B6","operatingLogo":"/static/images/airlines/B6.png","operatingName":"JetBlue Airways"},"departureTime":"2026-04-10T15:30:00","direction":"OUTBOUND","duration":{"iso8601":"PT6H10M","minutes":370},"flight":{"marketingNumber":"723","operatingNumber":"723"},"segmentKey":"c52f4148","originCode":"JFK","destinationCode":"LAX"}],"price":{"base":238.32,"currency":"USD","fees":0,"taxes":48.7,"total":287.02},"terms":{"changeable":true,"refundable":false,"summary":[{"level":"warning","message":"Change fee applies"},{"level":"danger","message":"Non-refundable"}],"changeFee":{"pricing":{"display":{"amount":75,"currency":"USD"},"converted":false},"percent":null,"applicability":"beforeDeparture","label":"Change fee (before departure)"},"refundFee":null}},"passengers":[{"type":"","title":"","firstName":"TEST","lastName":"COLUMNS","gender":"M"}],"order":{"reference":{"orderId":"019c42c6-69b4-779b-a627-d8914743d509","airlineBookings":[{"airlineCode":"1G","pnr":""}]}},"contact":{"firstName":"TEST","email":"test.json@example.com"}}}]}}}},"400":{"description":"Bad request — invalid booking ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingFieldInvalidId":{"summary":"Missing field: invalid ID format","value":{"error":{"code":47002,"description":"Booking ID is required and must be a valid UUID","message":"booking not found","key":"pathParam.bookingId"}}},"validationInvalidId":{"summary":"Validation error: invalid ID format","value":{"error":{"code":47005,"description":"Validation failed: invalid ID format","message":"validation error: invalid ID format","key":"pathParam.bookingId"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"code":47001,"description":"Authentication failed","message":"unauthorized"}}},"credentialFailed":{"summary":"Credential resolution failed","value":{"error":{"code":47006,"description":"Authentication failed: credential resolution failed","message":"unauthorized: credential resolution failed"}}}}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"bookingNotFound":{"summary":"Booking not found","value":{"error":{"code":47002,"description":"The booking was not found","message":"booking not found","key":"pathParam.bookingId"}}},"pnrNotFound":{"summary":"PNR not found","value":{"error":{"code":47003,"description":"The PNR was not found","message":"PNR not found","key":"pathParam.bookingId"}}}}}}}}}},"/data/flights/airlines":{"get":{"tags":["Airlines"],"summary":"List airlines","description":"## Overview\n\nRetrieve a list of airlines with optional filtering by name, alliance, and active status.\n\n## When to Use\n\n- **Airline directory** - Build a searchable list of airlines for display or filtering\n- **Alliance filtering** - Filter airlines by alliance membership (Star Alliance, oneworld, SkyTeam)\n- **Active airlines** - Retrieve only currently operating airlines\n\n## What You Get\n\n- **Full airline records** including name, IATA/ICAO codes, country, alliance, and logo URL\n- **Alliance membership** for each airline\n- **Active status** to identify currently operating carriers\n- **Filtered results** based on query, alliance, and active status parameters\n\n## Quick Start\n\nCall with no parameters to get all airlines. Use `q` to search by name, `alliance` to filter by alliance, and `activeOnly=true` to exclude inactive carriers.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query (e.g., 'AA' or 'American')","example":"American"},{"name":"limit","in":"query","schema":{"type":"integer","default":20},"description":"Maximum number of results","example":20},{"name":"activeOnly","in":"query","schema":{"type":"boolean","default":true},"description":"Only return currently active airlines","example":true},{"name":"alliance","in":"query","schema":{"type":"string","enum":["star_alliance","oneworld","skyteam","vanilla_alliance"]},"description":"Filter by airline alliance","example":"star_alliance"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"airlines":{"type":"array","items":{"$ref":"#/components/schemas/Airline"},"description":"List of airlines matching the query"}}},"description":"List of airline result sets"}}},"example":{"data":[{"airlines":[{"active":true,"alliance":"oneworld","callsign":"AMERICAN","country":"United States","iata":"AA","icao":"AAL","logo":"/static/images/airlines/AA.png","name":"American Airlines"}]}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":401,"description":"Authentication failed","message":"unauthorized"}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":5000,"description":"Failed to retrieve airlines","message":"unable to process request"}}}}}}}},"/data/flights/airlines/iatas":{"get":{"tags":["Airlines"],"summary":"List airline IATA codes","description":"## Overview\n\nRetrieve a lightweight list of airline IATA codes with names for autocomplete and lookup purposes.\n\n## When to Use\n\n- **Autocomplete dropdowns** - Populate airline search inputs with a minimal list\n- **Client-side filtering** - Download the full list once and filter locally\n- **Code validation** - Build a lookup table of valid airline codes\n\n## What You Get\n\n- **IATA codes** for all airlines in the database\n- **Airline names** paired with each code\n- **Active filtering** available via the `activeOnly` parameter\n\n## Quick Start\n\nCall with no parameters to get all airline IATA codes and names. Use `activeOnly=true` to filter out inactive airlines.","parameters":[{"name":"activeOnly","in":"query","schema":{"type":"boolean","default":true},"description":"Only return currently active airlines","example":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"airlines":{"type":"array","items":{"$ref":"#/components/schemas/AirlineIATA"},"description":"List of airline IATA codes and names"}}},"description":"List of airline IATA result sets"}}},"example":{"data":[{"airlines":[{"iata":"AA","name":"American Airlines"},{"iata":"AF","name":"Air France"}]}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":401,"description":"Authentication failed","message":"unauthorized"}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":5000,"description":"Failed to retrieve airline codes","message":"unable to process request"}}}}}}}},"/data/flights/airports":{"get":{"tags":["Airports"],"summary":"Search airports","description":"## Overview\n\nSearch for airports by name, city, or IATA code using a text query. Returns matching airports for use in autocomplete and search inputs.\n\n## When to Use\n\n- **Airport autocomplete** - Power origin/destination search inputs with type-ahead suggestions\n- **Airport discovery** - Find airports in a city or region by name\n- **Search validation** - Look up airports before constructing a flight search request\n\n## What You Get\n\n- **Matching airports** ranked by relevance to the query\n- **IATA codes** for `legs[].origin` and `legs[].destination` on `POST /flights/rates`\n- **City and country** details for display purposes\n- **Geographic coordinates** for map-based interfaces\n\n## Quick Start\n\nProvide a `q` query string (minimum 2 characters) to search by airport name, city, or code. Returns matching airports ordered by relevance.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query (minimum 2 characters, e.g., 'JFK' or 'New York')","example":"JFK"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"airports":{"type":"array","items":{"$ref":"#/components/schemas/Airport"},"description":"List of airports matching the query"},"count":{"type":"integer","description":"Total number of airports matching the query"}}},"description":"List of airport result sets"}}},"example":{"data":[{"airports":[{"city":"New York","country":"United States","iata":"JFK","icao":"KJFK","lat":40.63980103,"lon":-73.77890015,"name":"John F Kennedy International Airport","state":"New York","tz":"America/New_York"}],"count":1}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":4002,"description":"Query parameter 'q' is required for airport search","message":"required request field is missing or wrong input"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":401,"description":"Authentication failed","message":"unauthorized"}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":5000,"description":"Failed to retrieve airports","message":"unable to process request"}}}}}}}},"/flights/bookings":{"get":{"tags":["Flight Bookings"],"summary":"List bookings","description":"## Overview\n\nList confirmed flight bookings owned by the authenticated user. Supports an optional PNR + last-name lookup for retrieving a single booking, and optional `customTags` filtering.\n\n## When to Use\n\n- **\"My bookings\" page** - Display the authenticated user's confirmed flight bookings\n- **PNR lookup** - Retrieve a single booking by `airlinePnr` and a passenger's `lastName`\n- **Tag filtering** - Narrow results with `customTags=KEY:VALUE` labels set at book time\n- **Booking management** - Build dashboards or list views of past and upcoming reservations\n\n## What You Get\n\n- **Confirmed bookings only** - Returns records persisted from the booking flow;\n- **Full booking objects** with status, journey, passengers, order reference, pricing, and optional `customTags`\n- **Sandbox isolation** - Sandbox and live bookings are scoped by the API key used\n\n## Key Features\n\n- **Owner-scoped**: Only returns bookings belonging to the authenticated user\n- **PNR + last-name lookup**: When both `airlinePnr` and `lastName` are supplied, returns a single matching booking; both are required together\n- **Custom tags filter**: Optional `customTags` query AND-filters on labels attached at `POST /flights/bookings`\n- **Stable response shape**: `data` is always an array containing exactly one element with a `bookings` array\n\n## Quick Start\n\nCall with no query parameters to list all bookings for the authenticated user. To look up a specific booking, pass both `airlinePnr` and `lastName`. Filter with `customTags=SOURCE:GOOGLE`.","parameters":[{"name":"airlinePnr","in":"query","required":false,"schema":{"type":"string"},"description":"Airline PNR (record locator) for single-booking lookup. Required together with `lastName`.","example":"ABC123"},{"name":"lastName","in":"query","required":false,"schema":{"type":"string"},"description":"Passenger last name for single-booking lookup. Required together with `airlinePnr`.","example":"SMITH"},{"name":"customTags","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by customTags. Comma-separated `KEY:VALUE` pairs (e.g. `SOURCE:GOOGLE,TIER:GOLD`); all pairs are joined with AND. Keys must match `^[A-Z0-9_-]+$`, up to 5 keys, value up to 255 characters. Value matching is case-insensitive.","example":"SOURCE:GOOGLE,TIER:GOLD"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"bookings":{"type":"array","items":{"$ref":"#/components/schemas/FlightBooking"},"description":"Confirmed bookings owned by the authenticated user. Empty array when the user has no bookings."}}},"description":"List of booking result sets (always exactly one element)"}}},"example":{"data":[{"bookings":[{"bookingId":"1297abe4-57c5-4605-b8e7-5caad983c4a7","status":"CONFIRMED","timestamp":"2026-02-09T14:20:32.416Z","journey":{"journeyKey":"a3bbe883fe3a4f6b","segments":[{"arrivalTime":"2026-04-10T18:40:00","carrier":{"marketingCode":"B6","marketingLogo":"/static/images/airlines/B6.png","marketingName":"JetBlue Airways","operatingCode":"B6","operatingLogo":"/static/images/airlines/B6.png","operatingName":"JetBlue Airways"},"departureTime":"2026-04-10T15:30:00","direction":"OUTBOUND","duration":{"iso8601":"PT6H10M","minutes":370},"flight":{"marketingNumber":"723","operatingNumber":"723"},"segmentKey":"c52f4148","originCode":"JFK","destinationCode":"LAX"}],"price":{"base":238.32,"currency":"USD","fees":0,"taxes":48.7,"total":287.02},"terms":{"changeable":true,"refundable":false,"summary":[{"level":"warning","message":"Change fee applies"},{"level":"danger","message":"Non-refundable"}],"changeFee":{"pricing":{"display":{"amount":75,"currency":"USD"},"converted":false},"percent":null,"applicability":"beforeDeparture","label":"Change fee (before departure)"},"refundFee":null}},"passengers":[{"type":"","title":"","firstName":"TEST","lastName":"SMITH","gender":"M"}],"order":{"reference":{"orderId":"019c42c6-69b4-779b-a627-d8914743d509","airlineBookings":[{"airlineCode":"1G","pnr":"ABC123"}]}},"contact":{"firstName":"TEST","email":"test.json@example.com"}}]}]}}}},"400":{"description":"Bad request — invalid PNR lookup parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingAirlinePnr":{"summary":"Missing airlinePnr","value":{"error":{"code":47007,"description":"A required query parameter is missing: airlinePnr","message":"missing required field: airlinePnr","key":"query.airlinePnr"}}},"missingLastName":{"summary":"Missing lastName","value":{"error":{"code":47008,"description":"A required query parameter is missing: lastName","message":"missing required field: lastName","key":"query.lastName"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":401,"description":"Authentication failed","message":"unauthorized"}}}}},"404":{"description":"Booking not found (PNR lookup only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":47002,"description":"The booking was not found","message":"booking not found"}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":57099,"description":"Failed to retrieve booking","message":"unable to process get booking request"}}}}}}},"post":{"tags":["Flight Bookings"],"summary":"2. Complete a booking","description":"## Overview\n\nComplete a flight reservation by confirming a prebook and processing payment. This is the final step in the booking flow.\n\n## When to Use\n\n- **Final booking confirmation** - Convert a prebook into a confirmed booking\n- **Payment completion** - Confirm with Stripe (`TRANSACTION_ID`) or bill an enabled **credit line** (`CREDIT`)\n- **After service selection** - Book after optionally attaching seats or baggage via the services endpoint\n\n## What You Get\n\n- **Confirmed booking** with a unique booking ID\n- **Payment confirmation** with transaction details\n- **Full itinerary** including all segments and passenger assignments\n- **Provider confirmation** reference number\n\n## Key Features\n\n- **Idempotent**: Returns the existing booking if one already exists for the given `prebookId`\n- **Payments**: Stripe uses `transactionId` from prebook or attach-services after SDK confirmation; credit line uses `CREDIT` with server-side eligibility checks\n- **Provider confirmation**: Finalizes the reservation on the provider side\n\n## Quick Start\n\n**Required fields**: `prebookId` (from `POST /flights/prebooks`), `payment` with `method` and, for Stripe, `transactionId`\n\n**Tip**: If you used `POST /flights/prebooks/{prebookId}/services` to attach ancillary services, use the new `transactionId` from that response, not the original prebook `transactionId`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlightBookingCreateRequest"},"examples":{"stripeAfterPaymentSdk":{"summary":"Stripe after Payment SDK","description":"`payment.method` is `TRANSACTION_ID`; use `transactionId` from prebook or attach-services after confirming with Stripe.","value":{"prebookId":"019d0674-834d-7db7-9c8b-93fe8e46e7b8","payment":{"method":"TRANSACTION_ID","transactionId":"tr_cts_t0LaZePPxdCM_Kyskafml"}}},"creditLine":{"summary":"Credit line","description":"`payment.method` is `CREDIT` when the account has an enabled credit line and payment bypass; omit `transactionId`.","value":{"prebookId":"019d0674-834d-7db7-9c8b-93fe8e46e7b8","payment":{"method":"CREDIT"}}}}}},"description":"Request body with `prebookId`, `payment`, and optional `customTags`. For Stripe, set `payment.method` to `TRANSACTION_ID` and pass the Stripe payment intent id in `payment.transactionId` (e.g. `tr_ABCzxy91C-a9W123`). For credit line, set `payment.method` to `CREDIT` and omit `transactionId` (server-side eligibility applies)."},"responses":{"201":{"description":"Booking created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/FlightBooking","description":"Confirmed booking record with status, journey, passengers, order reference, and payment details"},"message":{"type":"string","description":"Informational message about the booking (e.g. idempotency notice)"}}},"description":"Booking result array (always one item)"}}}}}},"400":{"description":"Bad request — invalid booking parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidFormatPassengerData":{"summary":"Invalid format: passenger data","value":{"error":{"code":45004,"description":"Invalid format: passenger data is invalid","message":"invalid format: invalid passenger data","key":"bodyRequest"}}},"invalidFormatCardRejected":{"summary":"Invalid format: card rejected","value":{"error":{"code":45040,"description":"Invalid format: card was rejected","message":"invalid format: card rejected","key":"bodyRequest.payment"}}},"invalidParamsSessionExpired":{"summary":"Invalid parameters: session expired","value":{"error":{"code":45063,"description":"Invalid parameters: the session has expired","message":"invalid parameters: session expired","key":"bodyRequest.prebookId"}}},"validationInvalidEmail":{"summary":"Validation: invalid email","value":{"error":{"code":45021,"description":"Validation error: invalid email format","message":"validation error: invalid email format","key":"bodyRequest.contact.email"}}},"validationTicketingInactive":{"summary":"Validation: ticketing inactive","value":{"error":{"code":45081,"description":"Validation failed: ticketing is inactive","message":"validation error: ticketing inactive","key":"bodyRequest"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"code":45028,"description":"Authentication failed","message":"unauthorized"}}},"credentialFailed":{"summary":"Credential resolution failed","value":{"error":{"code":45082,"description":"Authentication failed: credential resolution failed","message":"unauthorized: credential resolution failed"}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":45083,"description":"Forbidden: credential resolution failed","message":"forbidden: credential resolution failed"}}}}},"404":{"description":"Offer or booking not found / expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"offerExpired":{"summary":"Offer expired","value":{"error":{"code":45029,"description":"The offer has expired","message":"offer expired","key":"bodyRequest.prebookId"}}},"bookingExpired":{"summary":"Booking expired","value":{"error":{"code":45084,"description":"The booking has expired","message":"expired: booking expired","key":"bodyRequest.prebookId"}}},"bookingNotFound":{"summary":"Booking not found","value":{"error":{"code":45033,"description":"the prebook was not found","message":"booking not found","key":"bodyRequest.prebookId"}}}}}}},"409":{"description":"Conflict — duplicate, ticketed, or invalid state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"duplicateBooking":{"summary":"Duplicate booking","value":{"error":{"code":45036,"description":"A duplicate booking was detected","message":"conflict: duplicate booking","key":"bodyRequest.prebookId"}}},"alreadyTicketed":{"summary":"Already ticketed","value":{"error":{"code":45087,"description":"The booking has already been ticketed","message":"conflict: already ticketed","key":"bodyRequest.prebookId"}}},"concurrentOperation":{"summary":"Concurrent operation","value":{"error":{"code":45035,"description":"A concurrent operation is already in progress","message":"conflict: concurrent operation","key":"bodyRequest.prebookId"}}}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internalError":{"summary":"Internal error","value":{"error":{"code":55015,"description":"An internal server error occurred","message":"internal server error"}}},"unableToProcess":{"summary":"Unable to process","value":{"error":{"code":55099,"description":"Failed to create booking","message":"unable to process booking request"}}}}}}},"502":{"description":"Provider error during booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"providerAuthFailedPayment":{"summary":"Provider auth failed: payment","value":{"error":{"code":55004,"description":"Provider auth failed: payment failed","message":"provider auth failed: payment failed","key":"bodyRequest"}}},"providerTimeoutGds":{"summary":"Provider timeout: GDS rejection","value":{"error":{"code":55018,"description":"Provider timeout: GDS rejection","message":"provider timeout: GDS rejection"}}},"providerUnavailConnection":{"summary":"Provider unavailable: connection failed","value":{"error":{"code":55029,"description":"Provider unavailable: connection to provider failed","message":"provider unavailable: connection failed"}}},"providerErrorTicketing":{"summary":"Provider error: ticketing failed","value":{"error":{"code":55014,"description":"Provider error: ticketing failed","message":"provider error: ticketing failed","key":"bodyRequest"}}},"providerErrorQueuePlacement":{"summary":"Provider error: queue placement failed","value":{"error":{"code":55034,"description":"Provider error: queue placement failed","message":"provider error: queue placement failed","key":"bodyRequest"}}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"cacheUnavailable":{"summary":"Cache unavailable","value":{"error":{"code":55035,"description":"The booking cache is unavailable","message":"cache unavailable"}}},"serviceUnavailable":{"summary":"Service unavailable","value":{"error":{"code":55036,"description":"The booking service is temporarily unavailable","message":"service unavailable"}}}}}}}}}},"/flights/prebooks":{"post":{"tags":["Flight Bookings"],"summary":"1. Create a checkout session (PREBOOK)","description":"## Overview\n\nInitiate a flight booking session by reserving the offer with the provider, creating a payment intent when you use the Stripe SDK, and discovering available ancillary services — all in a single request.\n\n## When to Use\n\n- **Start the booking flow** once a user has confirmed their flight selection\n- **Collect passenger details** and initiate payment processing\n- **Discover add-ons** like seat selection and extra baggage before final confirmation\n\n## What You Get\n\n- **Prebook ID** required to complete the booking at `/flights/bookings`\n- **Payment intent** (`transactionId`, `secretKey`) when `usePaymentSdk` is true — for Stripe SDK integration\n- **Credit line snapshot** (`creditLine` in the response) when you set `includeCreditBalance: true` and your account has an enabled credit line with payment bypass\n- **Available services** (`servicesAttachable`) including seats and baggage options\n- **Booking confirmation** from the provider with reservation details\n\n## Key Features\n\n- **End-to-end prebook flow**: Verifies offer → payment setup (Stripe payment intent or credit line) → books with provider → fetches services\n- **Payment options**: `usePaymentSdk: true` uses the Stripe SDK. `usePaymentSdk: false` is allowed when your user has **payment bypass** and an **enabled credit line** (no Stripe intent; call `/flights/bookings` with `payment.method: CREDIT`)\n- **Ancillary services**: Returns attachable services (seats, baggage) that can be added before final booking\n- **Same shape as /book**: Uses `offerId` instead of `prebookId`\n\n## Quick Start\n\n**Required fields**: `offerId` (from search/verify), `contact` (name, email, phone), `passengers` (with birthday, document, and name details).\n\n**Payment**: Send `usePaymentSdk: true` for Stripe (typical). Send `usePaymentSdk: false` when paying on credit line (requires payment bypass); otherwise you receive a validation error.\n\n**Tip**: Use the `servicesAttachable` in the response to offer seat selection or extra baggage before calling `/flights/bookings`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offerId","contact","passengers"],"properties":{"offerId":{"type":"string","description":"The offerId from the search results (msgpack-encoded; unpacks to provider offerId)","example":"h6NwaWTZJDAxOWQwNjZhLWNjMTktNzcyNi04ODM1LTEyMjFjNWRjN2UxNaJ0cMtAh471wo9cKaJtdctAJAAAAAAAAKNjdXKjVVNEo3VpZM0CeaJkZKoyMDI2LTA3LTAyonJkqjIwMjYtMDgtMDI="},"usePaymentSdk":{"type":"boolean","description":"If true, a Stripe payment intent is created (`transactionId`, `secretKey`). If false, payment bypass must apply and the account must have an enabled credit line (no Stripe intent); otherwise the request is rejected.","default":true,"example":true},"includeCreditBalance":{"type":"boolean","description":"Optional flag to include credit line information in the response. When set to true, credit line details will be returned if the user has a credit line available.","example":false},"payment":{"type":"object","description":"Payment configuration options","properties":{"descriptorSuffix":{"type":"string","description":"Suffix appended to the Stripe payment descriptor (visible on customer's bank statement)","example":"FLIGHT"},"paymentMethodConfiguration":{"type":"string","description":"Stripe Payment Method Configuration ID (pmc_...) controlling which payment methods Payment Element presents for this PaymentIntent.","example":"pmc_1J2K3L4M5N6O7P8Q"}}},"voucherCode":{"type":"string","description":"An optional voucher code to apply discounts to the booking. The vouchers API allows creation of these discounts"},"contact":{"type":"object","description":"Primary contact person for the booking (receives confirmation emails)","required":["firstName","lastName","email","phoneNumber"],"properties":{"email":{"type":"string","description":"Contact email address for booking confirmation","example":"j.doe@example.com"},"firstName":{"type":"string","description":"Contact first name","example":"John"},"lastName":{"type":"string","description":"Contact last name","example":"Doe"},"middleName":{"type":"string","description":"Contact middle name (optional)","example":"Joshua"},"phoneCountryCode":{"type":"string","description":"Phone country code without + (e.g. 1 for US, 33 for France)","example":"33"},"phoneNumber":{"type":"string","description":"Phone number without country code","example":"670-355-3640"}}},"passengers":{"type":"array","description":"List of passengers travelling. Length must match the adults+children+infants counts from the search.","items":{"type":"object","properties":{"birthday":{"type":"string","description":"Date of birth (YYYY-MM-DD)","example":"1996-04-28"},"documentExpiry":{"type":"string","description":"Travel document expiry date (YYYY-MM-DD)","example":"2030-04-28"},"documentIssueCountry":{"type":"string","description":"ISO country code of the document issuing country","example":"US"},"documentNumber":{"type":"string","description":"Travel document number","example":"123456789"},"documentType":{"type":"string","description":"Type of travel document (e.g. passport, id_card)","example":"passport"},"firstName":{"type":"string","description":"Passenger first name (as on travel document)","example":"John"},"gender":{"type":"string","description":"Passenger gender: M or F","example":"M"},"lastName":{"type":"string","description":"Passenger last name (as on travel document)","example":"Doe"},"middleName":{"type":"string","description":"Passenger middle name (optional)","example":"Joshua"},"nationality":{"type":"string","description":"Passenger nationality as ISO country code","example":"US"},"passengerType":{"type":"integer","description":"Passenger type: 0 = adult, 1 = child, 2 = infant","example":0},"loyaltyPrograms":{"type":"array","description":"Frequent flyer / loyalty programs for this passenger (Sabre and Travelport only; ignored for Atlas).","items":{"type":"object","required":["airlineCode","programNumber"],"properties":{"airlineCode":{"type":"string","description":"IATA airline code of the loyalty program (e.g. AA, BA, LH)","example":"BA"},"programNumber":{"type":"string","description":"Frequent flyer number / membership ID","example":"BA1234567"}}}}}}}}},"example":{"offerId":"h6NwaWTZJDAxOWQwNjZhLWNjMTktNzcyNi04ODM1LTEyMjFjNWRjN2UxNaJ0cMtAh471wo9cKaJtdctAJAAAAAAAAKNjdXKjVVNEo3VpZM0CeaJkZKoyMDI2LTA3LTAyonJkqjIwMjYtMDgtMDI=","usePaymentSdk":true,"includeCreditBalance":false,"payment":{"descriptorSuffix":"FLIGHT"},"contact":{"email":"j.doe@example.com","firstName":"John","lastName":"Doe","middleName":"Joshua","phoneCountryCode":"33","phoneNumber":"670-355-3640"},"passengers":[{"birthday":"1996-04-28","documentExpiry":"2030-04-28","documentIssueCountry":"US","documentNumber":"123456789","documentType":"passport","firstName":"John","gender":"M","lastName":"Doe","middleName":"Joshua","nationality":"US","passengerType":0,"loyaltyPrograms":[{"airlineCode":"BA","programNumber":"BA1234567"}]}]}}},"description":"Offer, passenger, contact, and payment configuration to initiate a prebook"},"responses":{"200":{"description":"Prebook created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"prebookId":{"type":"string","description":"Unique prebook identifier — use this in /bookings to complete the booking"},"booking":{"$ref":"#/components/schemas/FlightBooking","description":"Booking record created with the provider, including journey, passengers, and order reference"},"servicesAttachable":{"type":"object","properties":{"expiresAt":{"type":"string","description":"Expiry time for attaching services (ISO 8601)"},"groups":{"type":"array","description":"Groups of available ancillary services","items":{"type":"object","properties":{"available":{"type":"boolean","description":"Whether any services in this group are currently available"},"category":{"type":"string","description":"Service category (e.g. seat, baggage)"},"label":{"type":"string","description":"Human-readable group label"},"services":{"type":"array","items":{"type":"object","properties":{"serviceId":{"type":"string","description":"Unique service identifier (use in attachService)"},"name":{"type":"string","description":"Service name (e.g. Seat 7A)"},"category":{"type":"string","description":"Service category (e.g. seat, baggage)"},"passengerType":{"type":"string","description":"Applicable passenger type (ALL, ADT, CHD, INF)"},"segmentKey":{"type":"string","description":"Links to the segment this service applies to"},"pricing":{"$ref":"#/components/schemas/FlightItemPricing","description":"Price of this service (amount 0 means included)"},"metadata":{"type":"object","description":"Category-specific metadata. Contains exactly one of `seat` (when category is `seat`) or `baggage` (when category is `baggage`).","properties":{"seat":{"type":"object","description":"Seat details — present only when the service category is `seat`","properties":{"available":{"type":"boolean","description":"Whether this seat is currently available for selection"},"position":{"type":"string","description":"Physical position in the row (e.g. window, middle, aisle)"},"seatColumn":{"type":"string","description":"Column letter (e.g. A, B, C)"},"seatNumber":{"type":"string","description":"Full seat label (e.g. 1A)"},"seatRow":{"type":"integer","description":"Row number"},"seatType":{"type":"string","description":"Seat class/type (e.g. standard, extra_legroom, exit_row)"}}},"baggage":{"type":"object","description":"Baggage details — present only when the service category is `baggage`","properties":{"bagType":{"type":"string","description":"Type of bag (e.g. checked, cabin)"},"pieces":{"type":"integer","description":"Number of bag pieces included"},"weightKg":{"type":"number","description":"Weight allowance in kilograms"}}}}}}},"description":"Available services in this group"}}}}},"description":"Ancillary services available to attach before booking (seats, baggage, etc.)"},"price":{"type":"number","description":"Total price to charge (in the currency field)"},"currency":{"type":"string","description":"ISO 4217 currency code for price and secretKey"},"transactionId":{"type":"string","description":"When `usePaymentSdk` was true: Stripe transaction ID — use as `payment.transactionId` with `payment.method: TRANSACTION_ID` when calling `/flights/bookings`. Empty or omitted when prebooking on a credit line only."},"secretKey":{"type":"string","description":"When `usePaymentSdk` was true: Stripe payment intent client secret — use with the Stripe SDK before calling `/flights/bookings`"},"publishableKey":{"type":"string","nullable":true,"description":"When `usePaymentSdk` was true: Stripe publishable key (null if not applicable)"},"offerId":{"type":"string","description":"The offerId used to create this prebook"},"voucherCode":{"type":"string","description":"Represents the unique code used to redeem a voucher during the transaction."},"voucherTotalAmount":{"type":"string","description":"Specifies the total monetary value or discount amount provided by the voucher."},"paymentTypes":{"type":"array","items":{"type":"string"},"description":"Available payment methods for completing this prebook at `/flights/bookings`. Possible values: `TRANSACTION_ID` (use the returned Stripe `transactionId`), `CREDIT` (charge the account credit line), `ACC_CREDIT_CARD` (account-stored card via Adyen or Stripe), `WALLET` (Stripe wallet/saved payment method)."}}},"description":"Prebook result array (always one item)"}}},"example":{"data":[{"prebookId":"019d0674-834d-7db7-9c8b-93fe8e46e7b8","booking":{"timestamp":"2026-03-19T14:16:40Z","journey":{"journeyKey":"30073d47d441f174","segments":[{"segmentKey":"b4cd7e77","originCode":"JFK","originName":"John F. Kennedy International Airport","destinationCode":"FRA","destinationName":"Frankfurt Main Airport","departureTime":"2026-07-02T16:10:00","arrivalTime":"2026-07-03T05:55:00","direction":"OUTBOUND","duration":{"iso8601":"PT7H45M","minutes":465},"flight":{"marketingNumber":"2017","operatingNumber":"2017"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"35125125","originCode":"FRA","originName":"Frankfurt Main Airport","destinationCode":"CDG","destinationName":"Charles de Gaulle International Airport","departureTime":"2026-07-03T08:30:00","arrivalTime":"2026-07-03T09:50:00","direction":"OUTBOUND","duration":{"iso8601":"PT1H20M","minutes":80},"flight":{"marketingNumber":"4265","operatingNumber":"4265"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"f15d5c4e","originCode":"CDG","originName":"Charles de Gaulle International Airport","destinationCode":"FRA","destinationName":"Frankfurt Main Airport","departureTime":"2026-08-02T08:25:00","arrivalTime":"2026-08-02T09:55:00","direction":"INBOUND","duration":{"iso8601":"PT1H30M","minutes":90},"flight":{"marketingNumber":"4292","operatingNumber":"4292"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}},{"segmentKey":"7eccefc8","originCode":"FRA","originName":"Frankfurt Main Airport","destinationCode":"JFK","destinationName":"John F. Kennedy International Airport","departureTime":"2026-08-02T11:25:00","arrivalTime":"2026-08-02T14:10:00","direction":"INBOUND","duration":{"iso8601":"PT8H45M","minutes":525},"flight":{"marketingNumber":"2016","operatingNumber":"2016"},"carrier":{"marketingCode":"DE","marketingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","marketingName":"Condor Flugdienst","operatingCode":"DE","operatingLogo":"https://sandbox.nuitee.flights/static/images/airlines/DE.png","operatingName":"Condor Flugdienst"}}],"pricing":{"display":{"total":740.27,"currency":"USD","base":421.87,"fees":0,"taxes":318.4,"perPassenger":{"adult":{"base":421.87,"currency":"USD","fees":0,"taxes":318.4,"total":740.27},"child":{"base":0,"currency":"USD","fees":0,"taxes":0,"total":0},"infant":{"base":0,"currency":"USD","fees":0,"taxes":0,"total":0}}},"converted":true},"terms":{"changeable":true,"refundable":false,"summary":[{"level":"warning","message":"Change fee applies"},{"level":"danger","message":"Non-refundable"}],"changeFee":{"pricing":{"display":{"amount":75,"currency":"USD"},"converted":false},"percent":null,"applicability":"beforeDeparture","label":"Change fee (before departure)"},"refundFee":null}},"passengers":[{"firstName":"John","lastName":"Doe","middleName":"Joshua","birthday":"1996-04-28","gender":"M","nationality":"US","documentType":"passport","documentNumber":"123456789","documentIssueCountry":"US","documentExpiry":"2030-04-28"}],"order":{"reference":{"orderId":"OQTYXX","airlineBookings":[{"airlineCode":"DE","airlineName":"Condor Flugdienst","airlinePnr":"DCDE"}]}},"contact":{"firstName":"John","email":"j.doe@example.com"}},"price":740.27,"currency":"USD","transactionId":"tr_cts_WaTMwICRB0h_dOfyvLvvN","secretKey":"pi_3TChNEA4FXPoRk9Y1hbH6uVq_secret_CRhCAan4jSlXcwLs8N3r1qN6D","servicesAttachable":{"expiresAt":"2026-03-19T14:31:42.493Z","groups":[{"available":true,"category":"seat","label":"Seat Selection","services":[{"serviceId":"g6Rwc2lk2SQwMTlkMDY3NC1hYWY1LTczMjktODhiNy03OTdlNTc5YWJmZjWhcMtANdR64UeuFKFjo1VTRA==","name":"Seat 7A","category":"seat","passengerType":"ALL","segmentKey":"35125125","pricing":{"display":{"amount":21.83,"currency":"USD"},"converted":true},"metadata":{"seat":{"available":true,"position":"window","seatColumn":"A","seatNumber":"7A","seatRow":7,"seatType":"extra_legroom"}}},{"serviceId":"g6Rwc2lk2SQwMTlkMDY3NC1hYWY1LTczMjktODhiNy03OTdmZmYzMTczMGWhcMtANdR64UeuFKFjo1VTRA==","name":"Seat 7B","category":"seat","passengerType":"ALL","segmentKey":"35125125","pricing":{"display":{"amount":21.83,"currency":"USD"},"converted":true},"metadata":{"seat":{"available":true,"position":"middle","seatColumn":"B","seatNumber":"7B","seatRow":7,"seatType":"standard"}}}]},{"available":true,"category":"baggage","label":"Extra Baggage","services":[{"serviceId":"g6Rwc2lk2SQwMTlkMDY3NC1iYWcxLTczMjktODhiNy04OTdlNTc5YWJmZjWhcMtANdR64UeuFKFjo1VTRA==","name":"Standard Check In Baggage 10kg","category":"baggage","passengerType":"ALL","segmentKey":"35125125","pricing":{"display":{"amount":13.62,"currency":"USD"},"converted":true},"metadata":{"baggage":{"bagType":"checked","pieces":1,"weightKg":10}}}]}]},"voucherCode":"createvoucher83","voucherTotalAmount":20,"paymentTypes":["TRANSACTION_ID","CREDIT","WALLET"]}]}}}},"400":{"description":"Bad request — missing or invalid prebook parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingOfferId":{"summary":"Missing offerId","value":{"error":{"code":43001,"description":"field 'OfferID' is required","message":"required prebook field is missing","key":"bodyRequest.offerID"}}},"invalidParametersInvalidId":{"summary":"Invalid parameters: invalid ID format","value":{"error":{"code":43007,"description":"Invalid prebook parameters: the ID format is invalid","message":"invalid parameters: invalid ID format","key":"bodyRequest.offerId"}}},"validationSessionExpired":{"summary":"Validation error: session expired","value":{"error":{"code":43015,"description":"Prebook validation failed: the session has expired","message":"prebook validation error: session expired","key":"bodyRequest.offerId"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"code":43003,"description":"Authentication failed","message":"unauthorized"}}},"credentialFailed":{"summary":"Credential resolution failed","value":{"error":{"code":43016,"description":"Authentication failed: credential resolution failed","message":"unauthorized: credential resolution failed"}}}}}}},"404":{"description":"Offer expired, not found, or session expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notFoundOfferExpired":{"summary":"Not found: offer expired","value":{"error":{"code":43004,"description":"The offer has expired. Please search for new flights","message":"offer expired","key":"bodyRequest.offerId"}}},"expiredOfferExpired":{"summary":"Expired: offer expired","value":{"error":{"code":43017,"description":"The offer has expired","message":"expired: offer expired","key":"bodyRequest.offerId"}}},"expiredSessionExpired":{"summary":"Expired: session expired","value":{"error":{"code":43019,"description":"Expired: the session has expired","message":"expired: session expired","key":"bodyRequest.offerId"}}}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":53099,"description":"Failed to create prebook","message":"unable to process prebook request"}}}}},"502":{"description":"Provider error during prebook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"providerAuthFailedFlightInfoChanged":{"summary":"Flight info changed","value":{"error":{"code":53001,"description":"Provider auth failed: flight information has changed","message":"provider auth failed: flight info changed","key":"bodyRequest"}}},"providerAuthFailedOfferExpired":{"summary":"Provider auth failed: offer expired","value":{"error":{"code":53016,"description":"Provider auth failed: the offer has expired","message":"provider auth failed: offer expired","key":"bodyRequest"}}},"providerErrorOfferNotFound":{"summary":"Provider error: offer not found","value":{"error":{"code":53019,"description":"Provider error: the offer was not found","message":"provider error: offer not found","key":"bodyRequest"}}},"providerErrorConnection":{"summary":"Provider connection failed","value":{"error":{"code":53011,"description":"Provider error: connection to provider failed","message":"provider error: connection failed","key":"bodyRequest"}}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"cacheUnavailable":{"summary":"Cache unavailable","value":{"error":{"code":53013,"description":"The prebook cache is unavailable","message":"prebook cache unavailable"}}},"providerDisabled":{"summary":"Provider disabled","value":{"error":{"code":53014,"description":"The prebook provider is disabled","message":"prebook provider disabled"}}},"serviceUnavailable":{"summary":"Service unavailable","value":{"error":{"code":53015,"description":"The prebook service is temporarily unavailable","message":"prebook service unavailable"}}}}}}}}}}}}