Skip to main content

Changelog

2026-09-28 — Public developer portal​

The docs are now public at ndc.retailaer.com/docs/. The sandbox API uses https://ndc.retailaer.com/24.4/<Message>, OAuth tokens use /oauth/token, and self-service notification subscriptions use /subscriptions. API calls still require an airline-issued OAuth token or API key. The OpenAPI specification and downloadable Postman environment use the same public host.

Changelog

This documentation is generated from @oms/ndc-24-4; the changelog tracks the documented API surface and the docs site.

24.4 — updates since v2​

Each entry turns a documented limit into working behaviour; the Capabilities page shows the current status and remaining limits.

  • Travel documents are kept in full (Order with instant payment — now Supported). Pax/IdentityDoc on an OrderCreateRQ used to be reduced to a nationality and a masked number; everything else was dropped, so the airline could never produce APIS data for a booking it had sold. The whole document is now stored: its type (IATA PADIS code list 7365), number, citizenship, issuing and residence countries, issue and expiry dates, the given, middle, sur- and suffix names and the title as written on the document, birth date and birthplace, and gender (ICAO Doc 9303 F/M/U/X). It is treated as sensitive personal data: the number is encrypted at rest, it is erased once the trip is past, and it is readable in the clear only by an airline senior agent or supervisor who states a reason — recorded as an audit action. Nothing changes on the wire about secrecy. OrderViewRS now states the document the airline holds — type, citizenship, issuing country, expiry and holder surname — with the number masked. The number you send is in no response, not even to the seller that sent it. It rides the OrderViewRS family only: ServiceListRS, SeatAvailabilityRS and ServiceDeliveryRS state the passengers without it. A document the airline cannot name is refused rather than stored on a guess: new errors identity_document_type_unknown (PADIS 9321 718), identity_document_country_invalid (109) and identity_document_invalid (914, which also covers a value longer than IdentityDocType allows) — see Errors. The identity_document_masked warning stays, and now says the document is stored in full and shown masked; the new identity_document_not_shown warning says when the airline holds a document it cannot name, so silence is never read as "no document on file". A document is taken at OrderCreateRQ only. One sent on OrderChangeRQ (including UpdatePax) or OrderReshopRQ is refused with identity_document_not_updatable rather than read and dropped — you are never told a change succeeded while the airline discarded the document. How long it is kept is on the Capabilities page with the rest of the limits: erased once the trip is past the airline's retention window, re-derived from the order so a date change moves it. Also stated there, because they bound what this guarantee is worth: nothing files APIS data with a border authority or a DCS; the visas a document may nest (IdentityDoc/Visa), AddlName, RedressCase and FOID are not read; and the encryption key has no rotation path today.

  • Fare rules before booking; offers quote the brand policy (Offer conditions and restrictions — still Partial, materially closer). Every flight offer now carries its fare brand's own conditions — the airline's brand policy, the terms it applies once booked — instead of the supplier's base-fare conditions: Light is not changeable, Plus is refundable, every brand is cancellable and renameable. An offer whose brand policy cannot be read keeps the supplier's conditions and says so. The supplier's single change / cancellation fee is no longer quoted on the offer (the airline's fees go by the time before departure). Those conditions are recorded on the order at booking, so a booking is serviced by the terms it was SOLD under and not by a later change to the policy; an order booked before they were recorded is answered from today's policy and says so. Changeability is answered per direction, so a round trip sold under two brands states each direction's terms rather than its outbound's alone, and an order holding an unused Flexibility service is changeable under that service's terms whatever its fare says. OrderRulesRQ also answers a FareRef: a fare quoted on an offer and not booked yet. Fares are priced per offer, not filed, so FareRefText carries the OfferID the fare was quoted in, and FareBasisCode, Dep and Arrival must match that offer's fare. The answer holds the conditions the offer carries, the fare brand's conditions and the servicing terms per time-to-departure band — one Penalty per band and kind, in the order's currency. No Penalty (booked or quoted) states a fee for something the fare does not allow. New errors: fare_not_found (PADIS 9321 913) and fare_not_changeable (76H, a reshop of a fare that is not changeable); a FareRef without FareRefText is missing_offer_id; new warning fare_conditions_supplier — see Errors. What keeps it Partial is on the Capabilities page: cutoffs and band edges read departure times as UTC because the platform holds no airport time zones; the change fee is not keyed by fare brand, so it is charged on a brand whose published benefits say changes are free; fee amounts are the same raw number in every currency; and only changes are judged per direction — a cancel's refundability still comes from the outbound.

    What changes for you. The fare's changeable is now ENFORCED on this channel. OrderReshopRQ and the change actions on an order sold under a fare brand that does not allow changes — light in the seeded ladder — are refused with fare_not_changeable (76H) where they previously priced a change. This applies to orders already in your book, not only new ones. Two things still let such an order change: an open disruption (the airline moved the flight, so the fare does not bind), and an unused Flexibility service on the order. If you sell fares from the light rung, check your change flows against OrderRulesRQ before this release reaches you: it states, per direction, exactly what each order may do.

  • Offer content in your language (Localised offers — now Implemented). Send ResponseParameters/LangUsage/LangCode (or PayloadAttributes/PrimaryLangID): the airline's content — fare-brand names and benefits, station, cabin, service and partner-product names, seat descriptions, promotion names, captions — comes back in that language wherever the airline has translated it, in AirShoppingRS, OfferPriceRS, OrderViewRS, OrderReshopRS, ServiceListRS and SeatAvailabilityRS, and in English where it has not. Processing/LangUsage states the languages of the content; the new content_language_fallback warning names what stayed English. Error / Warning LangCode is now lower-case en, the form LangUsage uses.

  • Seat maps and seat changes on a booked order (Seat map — now Implemented; Seat options — now Partial). SeatAvailabilityRQ accepts an OrderRequest: the seat map of each of the order's flights. Availability — before and after the sale — is the flight's seat map less the seats any booking holds, whichever channel sold them (NDC, the web storefront, Manage-My-Booking, check-in); every channel claims its seat under the same lock, so one seat is sold once and the loser of a race is refused (over NDC: seat_unavailable) with nothing charged. A seat is chosen or changed with OrderReshopRQ (ServiceOrder/AddOfferItems with SeatCriteria on a booked flight) and accepted with OrderChangeRQ and PaymentFunctions, or bought directly with OrderChangeRQ AcceptSelectedQuotedOfferList from the order's seat map. The new seat comes back with its EMD; a paid seat given up is released under the cancellation terms and its value exchanged into the new seat (its EMD coupon E). Not included: after the sale a seat change is one passenger, one seat and one flight per message, and seats are reshopped and bought apart from extras.

  • Extras on a booked order (Reshop for ancillaries — now Partial). OrderReshopRQ with ServiceCriteria on a booked flight prices the airline's extras as frozen offers, per passenger; OrderChangeRQ accepts one with PaymentFunctions, or buys an item of the order's ALaCarteOffer directly. The extras come back with their EMDs — issued only once the payment is captured. A change is paid by card token, voucher or the seller's settlement plan: a settlement-plan payment after the sale is its own charge against the order, authorised against the agency's credit before the change is made (sale_not_recorded, HTTP 503: the sale's recording has not landed yet — retry), with its own commission — the agreement's percentage, or tier in the agreement's currency, on the charge's amount — and its own clearance; a leg left unfinished is finished by reconciliation only where that is provable — captured when the commit recorded it as paying, voided when it pays for no commit, otherwise handed to staff — and each refund releases the credit once. Not included: ground-transport rides (SHPMOD) and partner products are not added to a booked order, and a change cannot be paid by settlement plan under a flat-amount commission agreement (commission_rule_undefined: the agreement states no rule for it) or a tiered one stated in another currency (commission_currency_mismatch). A change whose voucher or loyalty payment fails to capture stands unpaid (no EMD) for staff.

  • What a booked order can buy (Shop for / with ancillaries — now Implemented). ServiceListRQ accepts an OrderRequest: the extras the order can add — the airline's published ancillaries, as Manage-My-Booking sells them — priced per passenger and flight, with their taxonomy codes, as an ALaCarteOffer the seller can buy from directly; OfferCriteria/ServiceCriteria select among them as for an offer. Rides stay with Transportation ancillaries and partner products with 3rd-party ancillaries.

  • The IATA Airline Taxonomy on airline services, seats, rides and partner products (Airline Taxonomy — Partial). Every airline service, the pre-reserved seat and every ride carries its node from the public IATA/EASD Airline Taxonomy Codeset in AirlineTaxonomy — the TaxonomyCode, with the codeset path as DescText (e.g. Flight / Checked Baggage / Bag, 1450) — on its ServiceDefinition, and a service or ride also on its offer / order item. Rides are Ground / Transport / Train (2E7C), Bus (2FA8) or Taxi (2DB4). ServiceListRQ now honours OfferCriteria/ServiceCriteria: TaxonomyCode (a parent node such as 13EC Checked Baggage selects the nodes below it), RFIC and RFISC, with IncludeInd false to exclude. Codes that changed: a checked bag is 1450 (was its parent 13EC), a meal 044C (03F0 is not in the codeset), priority boarding 25E4. Partner products (3rd-party ancillaries) carry the node of their marketplace category — lounge access 1B58, fast track 26AC, airport transfers 2CEC (Ground / Transport: cars and trains), train and bus transfers 2E7C / 2FA8, car rental 2D50, hotel vouchers 3138, eSIM 319C, travel insurance and baggage protection 3200, carbon offset 0E10 — on their ServiceDefinition (with RFIC / RFISC where the table states them) and their offer, priced and order items, and criteria select them like any other. Still Partial: food and drink, duty free, retail, airport parking, destination experiences and partner vouchers carry no node, because the codeset's node for them depends on where they are consumed (on board, in the terminal, in a lounge) or on what each one is, which no partner product records — they are listed without one and criteria that select by node, RFIC or RFISC do not return them.

  • Ancillaries at shop time and structured baggage (Shop for / with ancillaries). An AirShoppingRQ with OfferCriteria/ServiceCriteria returns each offer's ALaCarteOffer beside it — the airline's own services with the same items, ids and prices ServiceListRS gives for them, orderable in OfferPriceRQ / OrderCreateRQ, narrowed by RFIC / RFISC / TaxonomyCode (ground transport and partner products stay on ServiceListRQ). New Warnings services_limited, services_unavailable and services_refused say which offers came without them and why. IncludeInd false removes the offers whose fare brand includes that bag; service_criteria_partly_applied says what could not be judged. Fare brands now carry the airline's structured baggage allowance: BaggageAllowance (Checked / Carry on, pieces, kg per bag) with BaggageAssociations in AirShoppingRS and OfferPriceRS, and in OrderViewRS as a service per passenger and segment plus the e-ticket coupons' BaggageAllowanceRefID. A brand without a set allowance states none.

  • Personalised offers (now Implemented). Offers are priced for this airline's loyalty members and for your agreements as the authenticated seller — optionally with a negotiated programme's OfferCriteria/ProgramCriteria/ProgamContract/ContractID. Member pricing needs every fare-paying passenger to carry this airline's LoyaltyProgramAccount together with the account holder's name (Individual/GivenName + Surname); the airline checks both and looks the tier up itself. The order is bound to those accounts: OrderCreateRQ must carry them on the same travellers, or it is refused with member_pricing_not_eligible (753); an offer priced for a seller can be booked by that seller only. Passenger types reach pricing as sent (SRC, STU, …) with ages. New warnings: member_pricing_applied, member_pricing_not_applied, loyalty_pricing_unavailable, program_criteria_not_applied, program_account_not_applied — see Errors.

  • Price points with dynamic adjustments (now Implemented). The airline's NDC pricing rules apply to every shop, not only with a promotion code: discounts down and surcharges up, itemised in Price/Discount and Price/Surcharge (a named Breakdown per surcharge and its TotalAmount) on the offer and on each offer item, in AirShoppingRS, OfferPriceRS (also with services selected) and OrderViewRS. A fixed amount defined in another currency than your offers is not applied (never converted). New warnings: price_adjustments_unavailable, price_adjustment_currency_not_applied.

  • Every coupon on the e-ticket (Order retrieve — now Implemented). A traveller's trip with more than four flown segments is issued as a primary e-ticket plus conjunction tickets with consecutive numbers, four coupons each. OrderViewRS and OrderSalesInformationNotifRQ render them as one TicketDocInfo of up to four Tickets: CouponNumber restarts at 1 on each ticket, CouponSeqNumber orders the coupons across the journey, and PrimaryDocInd marks the primary ticket.

  • Loyalty points pay (Mixed payment instruments and Payment summary — now Implemented). PaymentFunctions accepts LoyaltyRedemption beside cards, vouchers and the settlement plan: the member's LoyaltyProgramAccount/AccountNumber plus a redemption certificate (CertificateNumber) the member issues in their loyalty account — their consent, one-time, capped and expiring; the account number alone never redeems points. The airline values the points at its programme's redemption rate (LoyaltyCurAmount, when sent, must match). A refund goes back to every leg that paid, newest first — points included — and OrderViewRS lists each payment and refund with its form of payment, points with the masked account. New errors (PADIS 9321 Code): loyalty_account_invalid (753), loyalty_certificate_invalid (706) and loyalty_points_insufficient (423) — see Errors.

  • The public sandbox is live (Sandbox — now Implemented). https://demo.retailaer.com answers NDC 24.4 messages at /ndc/24.4/<Message> with OAuth 2.0 client-credentials tokens from /api/ndc-api/oauth/token; sandbox credentials are issued by the airline. The supply behind it is simulated and says so in every response.

  • Settlement platform — limit restated. The remaining gap is the connection to IATA's BSP (the NDC services required by PAConf Resolution 850); settlement plans themselves work as documented.

  • Partner products (3rd-party ancillaries — now Partial). ServiceListRQ also lists the partner products the airline offers NDC sellers for the offer's trip, each with a ServiceDefinition naming the partner. A product's variants are separate offer items; a product with options is a service bundle whose options you choose with SelectedBundleServices (each option states what it adds to the price). Price them in OfferPriceRQ and order them with the flight in OrderCreateRQ, paid by the same payment; OrderViewRS shows each with its delivery status. A product is sold once per order and needs a contact email to be delivered to. Not sold over NDC: Arcube-connected products and marketplace bundles; adding a partner product to a booked order is not yet supported.

  • Fulfilment notifications for partner products (now Implemented). When a partner fulfils a partner product sold over NDC, subscribed sellers receive a ServiceDeliveryNotifRQ naming only that item, with the partner as the DeliveryProvider. Services delivered with no ticket or EMD behind them (a seat sold for nothing) are notified as before.

  • Ground transport timed to the flight (Transportation ancillaries — now Implemented). ServiceListRQ lists rail, coach and private-car rides to and from the airport, timed to the offer's departures and arrivals, priced per traveller (rail, coach) or per vehicle (car). Price them in OfferPriceRQ and order them with the flight in OrderCreateRQ. Simulated ride supply is flagged with the simulated-inventory Warning. Adding a ride to a booked order is not yet supported.

24.4 — seller-grade NDC (v2)​

What each capability covers, and its limits, is on the Capabilities page.

Sellers and access

  • Credentials are issued per seller (OAuth 2.0 client credentials). Every message checks the credentials' scopes, and the DistributionChain names the seller a call acts for — an aggregator may name the agencies it is granted.
  • Orders belong to the seller that booked them: another seller's order answers exactly like one that does not exist.

Shopping

  • AirShoppingRS carries fare brands, change and cancel conditions, promotions (promo codes) and multi-city / open-jaw journeys in typed DataLists.
  • ServiceListRQ lists the airline's ancillaries (bags, meals, wifi, priority, lounge, …) with IATA taxonomy codes where verified; SeatAvailabilityRQ returns seat maps with price points; OfferPriceRQ re-prices an offer together with the services and seats chosen.

Ordering and payment

  • OrderCreateRQ books one or more offers with services and seats, idempotent on CorrelationID + TrxID, and pays by PSP card token (with 3-D Secure), voucher, the seller's settlement plan, or a mix of them. Sent without PaymentFunctions, the order is held until its payment time limit and paid later with OrderChangeRQ.
  • Card numbers are refused (pan_not_accepted): pay with a token.
  • OrderViewRS shows passengers, segments, services, seats, tickets and EMDs with coupon status, payments, refunds and the seller's commission. OrderRetrieveRQ, OrderHistoryRQ and OrderListRQ (the seller's own orders, cursor-paged) read it back.

Servicing

  • OrderReshopRQ prices a date change, a name change or a cancellation (of the whole order or of items) as an offer with its differential, fees and refund; OrderChangeRQ accepts exactly that offer, pays a held order, or updates the booking contact. OrderRulesRQ returns a booked order's conditions, fees and cutoffs.
  • Refunds go back to the tenders that paid; a cancellation can return a reusable travel credit instead.

Notifications and delivery

  • Self-service subscriptions with signed deliveries and replay: OrderChangeNotifRQ for changes the airline makes (including an unpaid order cancelled at its payment time limit), ServiceStatusChangeNotifRQ and ServiceDeliveryNotifRQ as services are delivered. ServiceDeliveryRQ reports a booked order's delivery status.

Settlement and accounting

  • The PaymentClearance messages (clearance, cancellation, list, clearing history) and their notifications, over a simulated clearance manager.
  • The airline's accounting receives OrderSalesInformationNotifRQ on every sale, change, refund and void, and OrderClosingNotifRQ when an order closes.

Sandbox and documentation

  • The sandbox is live at https://demo.retailaer.com (messages at /ndc/24.4/<Message>, token at /api/ndc-api/oauth/token); the Postman environment points at it.
  • Every reference page says whether the airline implements the message — Implemented, Partial or Not implemented — read from the gateway's capability registry, and the Capabilities page names the sandbox scenario behind each capability.
  • New guides: Onboarding (credentials → shop → book and pay → cancel) and Notifications (subscribe, verify signatures, replay).
  • A Postman Negative tests folder: one request per documented error, each held to its documented answer by the gateway's own tests.
  • All 48 generated examples now validate against the original XSDs (the PaymentClearance family's types no longer collide with the Offers & Orders ones).

24.4 — initial release​

  • 48 NDC 24.4 services documented across seven domain groups: Shopping & Pricing, Order Management, Servicing & Delivery, Airline Profile, Interline, Payment Clearance, and Acknowledgement.
  • A reference page per message with a generated, XSD-validated request example, the paired response example, the top-level field model, and a copy-paste SDK snippet.
  • An OpenAPI 3.1 contract (/api/) rendered in-site with Redoc — one POST operation per request/notification, with application/xml bodies.
  • A Postman v2.1 collection plus sandbox and production environments, with OAuth token handling and saved example responses.
  • Narrative guides: getting started, core concepts, authentication, and errors.

Known limitations​

  • 38 of 48 generated examples validate against the original XSDs. The remaining ten (eight Payment Clearance messages plus OrderChangeNotifRQ and OrderRulesRQ) carry a minimal sample pending choice-group-aware example generation; they are flagged on their reference pages.
Versioning

A new documentation version is snapshotted when a future NDC schema set is adopted. Until then, 24.4 is the single published version.