Create offers
POST /json/{version}/offers searches flight availability and returns bookable offers. It is the JSON counterpart of the NDC IATA_AirShoppingRQ.
Two layouts of the same search exist:
POST /json/{version}/offers: the flat layout (data.viewisflat): a list of complete offers, each with its offer items.POST /json/{version}/offers/byJourney: the by-journey layout (data.viewisbyJourney): journeys grouped per trip direction with bookable fare options, suited to booking UIs.
Both endpoints accept the same request body and cache the same offers; only the JSON projection differs. Offers are per journey, so for a round trip the client picks one option per direction and prices them together with price offer.
Both return 201 Created on success.
Request
Section titled “Request”Content-Type: application/json is required.
| Field | Description |
|---|---|
originDestinations | One entry per trip direction: origin, destination (3-letter IATA codes), and departureDate (YYYY-MM-DD, not in the past). One entry for one-way, two for round trip. Departure dates must be in chronological order. A city-only code (NYC) automatically searches its metro’s airports. Set searchOriginMetro or searchDestinationMetro (optional booleans) on an entry to widen an airport code the same way. Offers carry their real airports. A metro round trip must return over the outbound’s airports; OfferPrice refuses any other pair with ERR-3003. Reshop and order change are airport-specific. |
passengers | One entry per traveler: type (ADT, CHD, or INF) and optional paxId. When paxId is omitted, IDs are synthesized as PX1..PXn in declaration order. Infants cannot exceed adults. See passengers. |
cabinTypeCode | Optional cabin filter: Y, C, W, or F. |
currency | Optional 3-letter ISO 4217 currency code. USD only for now; any other code is rejected. See payments. |
POST /json/v0/offersAuthorization: <bearer token from /auth/token>Content-Type: application/json
{ "originDestinations": [ { "origin": "SLC", "destination": "CHS", "departureDate": "2026-09-15" } ], "passengers": [ { "paxId": "PX1", "type": "ADT" } ], "cabinTypeCode": "Y"}For a round trip, add a second entry to originDestinations with the return date.
Response: flat layout
Section titled “Response: flat layout”data.offers lists each offer with offerId, ownerCode, expiresAt (UTC), totalPrice, and offerItems. Each offer item carries the flight (journey, segments), the fare (fare basis, bundle, benefits), and passengerPrices per passenger type. Flight times are local with no timezone suffix.
fare.bundleName and fare.benefits are JSON-only display conveniences so clients can render fare comparison without a catalog lookup.
{ "data": { "view": "flat", "pax": [ { "paxId": "PX1", "ptc": "ADT" } ], "offers": [ { "offerId": "OF-25a8bea9-89f5-11ea-98be-25340131a18b", "ownerCode": "MX", "expiresAt": "2026-09-15T12:00:00.000Z", "totalPrice": { "total": { "amount": 99, "currency": "USD" }, "base": { "amount": 91.5, "currency": "USD" }, "taxes": [ { "code": "US", "amount": { "amount": 7.5, "currency": "USD" } } ], "fees": [] }, "offerItems": [ { "offerItemId": "OFI-25a8bea9-89f5-11ea-98be-25340131a18b-0", "totalPrice": { "total": { "amount": 99, "currency": "USD" }, "base": { "amount": 91.5, "currency": "USD" }, "taxes": [ { "code": "US", "amount": { "amount": 7.5, "currency": "USD" } } ], "fees": [] }, "flight": { "journeyId": "JK1", "origin": "SLC", "destination": "CHS", "departureDateTime": "2026-09-15T08:00:00", "arrivalDateTime": "2026-09-15T12:00:00", "duration": "PT4H", "stops": 0, "flightNumbers": [ "MX101" ], "segments": [ { "marketingCarrier": "MX", "marketingFlightNumber": "101", "origin": "SLC", "destination": "CHS", "departureDateTime": "2026-09-15T08:00:00", "arrivalDateTime": "2026-09-15T12:00:00", "cabinTypeCode": "Y", "rbd": "Y" } ] }, "fare": { "fareBasisCode": "Y", "cabinTypeCode": "Y", "rbd": "Y", "priceClassRefId": "EZU", "paxRefIds": [ "PX1" ], "bundleName": "Nice", "benefits": [ { "label": "Carry-on bag", "included": true }, { "label": "Checked bag", "included": false } ] }, "passengerPrices": [ { "ptc": "ADT", "count": 1, "paxRefIds": [ "PX1" ], "price": { "total": { "amount": 99, "currency": "USD" }, "base": { "amount": 91.5, "currency": "USD" }, "taxes": [ { "code": "US", "amount": { "amount": 7.5, "currency": "USD" } } ], "fees": [] } } ] } ] } ] }, "error": null}Response: by-journey layout
Section titled “Response: by-journey layout”data.directions lists each trip direction with its journeys. Every journey carries the shared flight detail plus options[], the bookable fare variants with per-leg totalPrice, expiresAt, and fare detail. The client picks one option per direction (bundles may differ per direction).
{ "data": { "view": "byJourney", "pax": [ { "paxId": "PX1", "ptc": "ADT" } ], "directions": [ { "legIndex": 0, "origin": "SLC", "destination": "CHS", "departureDate": "2026-09-15", "journeys": [ { "flight": { "journeyId": "JK1", "origin": "SLC", "destination": "CHS", "departureDateTime": "2026-09-15T08:00:00", "arrivalDateTime": "2026-09-15T12:00:00", "duration": "PT4H", "stops": 0, "flightNumbers": [ "MX101" ], "segments": [ { "marketingCarrier": "MX", "marketingFlightNumber": "101", "origin": "SLC", "destination": "CHS", "departureDateTime": "2026-09-15T08:00:00", "arrivalDateTime": "2026-09-15T12:00:00", "cabinTypeCode": "Y", "rbd": "Y" } ] }, "options": [ { "offerId": "OF-25a8bea9-89f5-11ea-98be-25340131a18b", "offerItemId": "OFI-25a8bea9-89f5-11ea-98be-25340131a18b-0", "expiresAt": "2026-09-15T12:00:00.000Z", "totalPrice": { "total": { "amount": 99, "currency": "USD" }, "base": { "amount": 91.5, "currency": "USD" }, "taxes": [ { "code": "US", "amount": { "amount": 7.5, "currency": "USD" } } ], "fees": [] }, "fare": { "fareBasisCode": "Y", "cabinTypeCode": "Y", "rbd": "Y", "priceClassRefId": "EZU", "paxRefIds": [ "PX1" ], "bundleName": "Nice", "benefits": [ { "label": "Carry-on bag", "included": true }, { "label": "Checked bag", "included": false } ] }, "passengerPrices": [ { "ptc": "ADT", "count": 1, "paxRefIds": [ "PX1" ], "price": { "total": { "amount": 99, "currency": "USD" }, "base": { "amount": 91.5, "currency": "USD" }, "taxes": [ { "code": "US", "amount": { "amount": 7.5, "currency": "USD" } } ], "fees": [] } } ] } ] } ] } ] }, "error": null}Create offers errors
Section titled “Create offers errors”| Code | HTTP status | Cause |
|---|---|---|
ERR-1002 | 404 | Unsupported version segment in the path. |
ERR-1004 | 400 | Two originDestinations entries search the same airports on the same date. |
ERR-1005 | 422 | Request validation failed: bad date, duplicate paxId, infants exceeding adults, or out-of-order departure dates. |
ERR-1006 | 422 | Origin or destination is not a valid market. |
ERR-3000 | 404 | Referenced offer could not be found. |
ERR-3008 | 409 | The seller’s contracted fare for this market has not completed pricing verification. |
ERR-8000 | 401 | Missing or invalid API key or bearer token. |
ERR-8001 | 403 | API key not authorized for this request. |
ERR-8002 | 503 | Authentication store unavailable. |
ERR-2002 | 500 | Availability could not be processed upstream. |