JSON & XML API differences

Why JSON?

JSON is Breeze's native offer/order API format. Our NDC/XML API supports partners that need IATA XML messages. Both surfaces use the same underlying offer/order capability layer, but their wire contracts are intentionally different.

We adhere to IATA's defined XML schemas. In some cases, schema compliance requires XML to omit data or use extra reference lists. Our JSON structure is designed for application developers to consume.

This page only documents differences between our JSON and NDC/XML APIs. Refer to specific endpoint documentation pages for detailed API definitions.

Supported versions

API	Versions	Notes
JSON	v0, then v2	Scheduled JSON major versions use even numbers.
IATA XML / NDC	v25.4, then v26.2	Version is selected by the route, not a payload Version attribute. v21.3 (the 21.3.5 schema) is unsupported.

Visit our dedicated page to learn about our release schedule and support policy.

Types of differences

Area	JSON behavior	XML behavior	Integration impact
Routes	Resource routes such as POST /json/{version}/offers, GET /json/{version}/orders/{orderId}, and PATCH /json/{version}/orders/{orderId}.	Operation routes such as POST /ndc/{version}/AirShopping, OrderRetrieve, and OrderChange.	Integrators may prefer narrow-scope XML operations.
Response envelope	Every response uses { "data": ..., "error": ... }.	Success responses are operation-specific IATA_*RS XML documents. Errors also return XML with Error elements.	JSON clients can use one envelope parser. XML clients must parse each response root.
Documentation	JSON routes are exposed in Swagger/OpenAPI.	NDC XML routes are excluded from Swagger because opaque XML bodies are not useful in OpenAPI.	Use the JSON endpoint docs and Swagger for JSON; use our NDC/XML docs and IATA schemas for XML.
Data shape	Reuses top-level collections such as pax, journeys, services, payments, and tickets; fields use JSON casing.	Uses IATA structures such as Response, DataLists, OffersGroup, PaxList, namespaces, and schema element ordering.	Do not expect XML wrappers, namespaces, or IATA element names in JSON.
IDs and references	Uses resource IDs and arrays such as paxRefIds, journeyRefIds, and segmentRefIds.	Uses NDC references such as PaxRefID, ServiceDefinitionRefID, PaxJourneyRefID, PaxSegmentRefID, and generated NDC IDs.	IDs are not guaranteed to be interchangeable across API versions and surfaces.
Error body	error.code, error.title, and error.description in the JSON envelope.	IATA Error elements with the same Breeze ERR-* catalog code in XML form.	Error codes are shared; error payload shape is not.

Endpoint coverage

Capability	JSON	XML / NDC	Difference
Airline profile	No JSON endpoint yet.	AirlineProfile is implemented.	XML has this reference-data operation; JSON does not.
Offer search	POST /offers and POST /offers/byJourney.	AirShopping.	JSON has two response layouts for the same cached offers; XML has the NDC response shape.
Offer price	POST /offers/price.	OfferPrice.	Same pricing capability, different request and response shapes.
Order create	POST /orders.	OrderCreate.	Same booking capability, different payment and passenger/contact shapes.
Order retrieve	GET /orders/{orderId}.	OrderRetrieve.	Same retrieve capability, different OrderView projection.
Order list	GET /orders.	OrderList.	Same booking search capability, different pagination and arrival-data behavior.
Ancillaries	/offers/{offerId}/seats, /offers/{offerId}/services, /orders/{orderId}/seats, /orders/{orderId}/services.	SeatAvailability, ServiceList.	Same underlying ancillary quote service, different quote IDs and response structures.
Order change	PATCH /orders/{orderId}.	OrderChange.	Same change capability, but JSON uses typed change instructions while XML uses NDC order-change instructions.
Cancel order	POST /orders/{orderId}/cancel.	No dedicated OrderCancel route; cancellation rides OrderChange.	JSON exposes a dedicated cancel route. XML cancellation follows the NDC OrderChangeRQ flow.
Reshop and quote	POST /orders/{orderId}/reshop, POST /orders/{orderId}/quote.	OrderReshop, OrderQuote.	Same new-itinerary and quote flow, different selected-offer and price-differential shapes.

Offers and OfferPrice

Offer search request

Difference	JSON behavior	XML behavior	Why they differ
Cabin code	cabinTypeCode uses Breeze JSON cabin codes: Y, C, W, F.	OriginDestCriteria.CabinType.CabinTypeCode uses PADIS numeric codes: 1, 2, 4, 5.	JSON uses a compact app-facing vocabulary; XML follows the IATA wire vocabulary.
Currency	currency is a top-level JSON field. USD only for now.	Currency is read from ResponseParameters.CurParameter.CurCode. USD only for now.	See payments.
Trip criteria	originDestinations[] contains origin, destination, and departureDate.	FlightRequestOriginDestinationsCriteria.OriginDestCriteria contains OriginDepCriteria and DestArrivalCriteria.	Same search criteria, different wire shape.
Passenger IDs	paxId is optional and synthesized when omitted.	PaxID is optional and synthesized when omitted.	Behavior is similar, but field names and nesting differ.

Both surfaces reject invalid dates, past departure dates, out-of-order origin-destination dates, duplicate passenger IDs, and infant counts greater than adult counts.

Offer search response

JSON has two projections of the same offer:

• POST /json/{version}/offers returns a flat data.offers[] list.
• POST /json/{version}/offers/byJourney returns data.directions[] grouped for booking UIs.

XML AirShoppingRS returns the IATA shape: DataLists, OffersGroup, per-passenger-type OfferItem rows, baggage and service definitions, price classes, and IATA references.

JSON also includes app-facing fare display fields such as fare.bundleName and fare.benefits. XML exposes the underlying NDC offer, price class, baggage, and service-definition structures instead.

OfferPrice request

Difference	JSON behavior	XML behavior	Integration impact
Selected offers	selections[] contains offerId and offerItemIds.	SelectedOfferList.SelectedOffer contains OfferRefID, OwnerCode, and SelectedOfferItem.	XML callers must include OwnerCode; JSON does not require it in the body.
Passengers	passengers[] is required.	DataLists.PaxList is optional when passenger type can be derived from selected item references.	JSON callers always send passengers. XML callers may omit PaxList only when the selected NDC offer item IDs carry enough passenger-type information.
Response layout	Returns data.offer plus top-level pax and journeys.	Returns IATA_OfferPriceRS.Response.DataLists plus PricedOffer.	JSON avoids XML DataLists wrappers and puts reusable collections at the top level.

OfferPrice is exclusively used for new orders. Existing orders must be priced through a Reshop and Quote flow.

Orders

OrderCreate payment

Difference	JSON behavior	XML behavior	Integration impact
Hold booking	payment is required; use { "type": "Hold" } for a hold.	Omitted PaymentFunctions is treated as a hold.	JSON callers must be explicit. XML callers can create a hold by omitting payment functions.
Card payment	Uses payment.type: "CreditCard".	Uses NDC PaymentFunctions / PaymentProcessingDetails / PaymentCard.	Same brands and sandbox test card; see payments.
Currency	Amounts are always USD.	Amount CurCode must be USD.	See payments.
Booking contacts	Request contact (single primary); response contacts[] with contactTypeCode.	Unreferenced ContactInfo = primary; Pax-referenced = per-passenger.	See contacts.
Passengers	JSON passengers[] with request gender Male/Female.	XML PaxList with GenderCode M/F (also accepts Male/Female).	See passengers.

OrderRetrieve response

JSON returns a flattened OrderView projection:

• order
• services
• pax
• contacts
• journeys
• payments
• tickets

XML returns IATA_OrderViewRS with Response.DataLists, Response.Order, optional TicketDocInfo, root-level PaymentFunctions, warnings, PayloadAttributes, and optional DistributionChain echo.

GET /orders | OrderList

Destination airport code

• IATA requirement: in IATA_OrderListRS, arrival data must include both arrival station and arrival date.
• XML data object: IATA_OrderListRS.Response.MatchedOrder.Arrival.ArrivalDate
• Applies to XML: v21.3, v24.1, v25.4, v26.2
• Limitation: the reservation-system booking search returns the arrival station, but not the arrival date.
• Decision: XML omits Arrival; JSON may return destination without arrival date.

Why we do not populate XML Arrival anyway:

• Arrival station is useful in JSON even when arrival date is unknown.
• Populating arrival date in XML would require retrieving individual orders, which is slow and expensive for list searches.
• Guessing arrival date from departure date would be wrong for overnight flights and other schedule edge cases.
• IATA Airline Retailing Maturity assessment requires strict XML compliance.

JSON example:

{
  "data": {
    "orders": [
      {
        "orderId": "P42SEA",
        "recordLocator": "P42SEA",
        "statusCode": "CONFIRMED",
        "departureDate": "2026-08-07",
        "flightNumber": "42",
        "origin": "BRO",
        "destination": "MCO",
        "sourceOrganizationCode": "AGENCY",
        "passengerName": {
          "surname": "David",
          "givenName": "Dieudonne"
        }
      }
    ],
    "page": {
      "pageSize": 1000,
      "lastIndex": 1000,
      "count": 1,
      "hasMore": false
    }
  },
  "error": null
}

Pagination

JSON behavior	XML behavior	Integration impact
Uses explicit cursor pagination: pageSize, lastIndex, page.count, and page.hasMore.	OrderListRS has no pagination contract, so the service walks upstream pages server-side up to a fixed cap and returns a warning when truncated.	JSON callers control paging. XML callers should narrow search filters when Warning code OL1001 is returned.

Filter support

JSON query parameters and XML OrderSearchFilterCriteria support the same practical search fields: agency organization code, passenger name, departure date, origin, destination, and flight number. XML rejects unsupported NDC filter blocks instead of silently broadening the search.

Ancillaries

JSON exposes separate resource routes for offer-scoped and order-scoped seat and service quotes. XML exposes the NDC SeatAvailability and ServiceList operations.

Difference	JSON behavior	XML behavior	Integration impact
Request shape	Offer-scoped routes take offerItemIds; order-scoped routes take optional orderItemIds.	RQs use NDC selected-offer or order references.	Use the ID shape returned by the same surface.
Quote IDs	JSON returns public ancillary offer item IDs in JSON service/seat structures.	XML returns NDC a-la-carte offer and offer item IDs such as seat/service selections.	Quote IDs encode identity only; price and availability are recomputed on commit.
Passenger scope	Offer-scoped JSON can synthesize passenger IDs; order-scoped JSON only uses supplied stable passenger refs.	XML uses NDC passenger references from the request and order view.	For post-booking ancillaries, use passenger refs from the retrieved order.

Reshop and quote

New sale and itinerary change use different pricing paths on both APIs:

Intent	JSON flow	XML flow
New sale	POST /offers or /offers/byJourney -> POST /offers/price -> POST /orders	AirShopping -> OfferPrice -> OrderCreate
Itinerary change	POST /orders/{orderId}/reshop -> POST /orders/{orderId}/quote -> PATCH /orders/{orderId}	OrderReshop -> OrderQuote -> OrderChange

JSON returns compact change amounts such as priceDifferential and itemChangeQuotes. XML returns the NDC IATA_OrderReshopRS shape with PriceDifferential.

Do not send reshop offer IDs to OfferPrice. The service rejects those IDs because reshop pricing accounts for changes to the existing order.