Distribution API Documentation

POST /distribution/v1/sessions is the only unauthenticated endpoint. It is protected by an HMAC signature instead of a Bearer token. The partner sends the following headers:

The canonical message that is signed is the newline-joined tuple:

Example using openssl:

All other endpoints require the minted token:

The token is granted a subset of scopes — the intersection of what the partner requests and what the partner is entitled to. Each endpoint requires a specific scope; a token missing the required scope receives 403 SCOPE_INSUFFICIENT.

Requests may include an optional X-Airline-ID header. When present, it must match the partner’s configured airline; a mismatch is rejected with 403 AUTHZ_FAILED. When absent, the airline is resolved from the partner record.

status on the order. You get it from Create Order, Get Order, Confirm Wallet Payment, Cancel Exchange, Cancel Infant Addition, and a successful Settle Exchange Payment or Settle Infant Addition Payment.

Seven other responses use a field of the same name for their own vocabulary: Commit Exchange, Add Infant, Add Ancillaries, the 202 of Settle Exchange Payment, of Settle Infant Addition Payment and of Settle Ancillary Addition Payment, and Refund Order. Each is described where it is returned. Do not resolve those values against the table below, even when they spell REFUNDED or PARTIALLY_REFUNDED.

A partner order moves through:

Before payment: CONFIRMED → ACTIVATED on payment, CONFIRMED → EXPIRED when the payment window elapses, CONFIRMED → CANCELLED when the order is cancelled first. There is no partner cancel endpoint, so you cannot drive CANCELLED yourself. It is not always airline-initiated either. If the payment system cancels the order’s payment intent, the order is cancelled with nobody acting on it, and the outstanding invoice is voided on the way, so invoice.status then reads CANCELLED rather than ISSUED. Do not read CANCELLED as "the airline cancelled us".

After payment, an airline-side refund moves ACTIVATED → PARTIALLY_REFUNDED → REFUNDED, or straight to REFUNDED when the whole order goes at once. Most of the time you will see ACTIVATED, plus the terminal EXPIRED and CANCELLED. The two refunded states appear only on orders the airline refunded for you.

status on each item in items[] (see Get Order). An order is a flat list of items: a flight for a passenger, an ancillary, a fee. This is the per-item state.

pax_segment_status on flight-leg anchors (see Get Order) is where the passenger stands on that leg. It is the only field that answers "did this person travel". status on the same row is the commercial life of the line item and flight_status is the airline’s operation on the aircraft; neither moves when a passenger boards.

A passenger travelled if the value is BOARDED or FLOWN. Take both, not just FLOWN. ARRIVED is not a value here at all: it belongs to the flight, not to the passenger.

Parse the field as an open set. Other values exist for legs that were refunded, exchanged, cancelled or expired, and new ones may appear; branch on the values above and treat the rest as "no travel answer for this leg": some of them, such as an owner transfer or an exchange still in flight, sit on a leg that is very much going to be flown.

status in the Refund Order response. This is a different field from the order status above, and it reuses two of the same words. It is exactly one of PROCESSING, REFUNDED or PARTIALLY_REFUNDED, and it describes the refund of the booking, never the state of the order.

PROCESSING means the refund was accepted and is still settling. REFUNDED and PARTIALLY_REFUNDED mean the booking side of the refund has completed. The credit reaches your wallet separately, so reconcile the money from GET /distribution/v1/wallet/transactions either way.

invoice.status (see Get Order). The invoice field is the most recently issued invoice for the order.

There is no ticket status value. ticketed (boolean, see Get Order) is true when every live flight leg on the order sits on a booking in a paid state and at least one of those legs carries an e-ticket number. It is an order-level flag, not a per-passenger one, so ticketed: true does not promise a number for every passenger. An infant travelling on an adult’s ticket has none, and Get Order Ticket returns a null eticket_number for such a passenger. Get Order Ticket applies its own gate: the order’s head booking must be paid and at least one passenger on it must carry an e-ticket number. A passenger added through Add Infant lives on a child booking, so an unsettled addition never blocks the ticket, and a settled one never appears in it. Read ticketed: true as the moment to call it, not as a guarantee of what it will answer.

flight_status on flight-leg items (see Get Order) reports the airline’s operation on the booked flight. When the flight behind an item cannot be resolved, the key is omitted rather than sent as null. Treat an absent flight_status as unknown and re-read it. Never default it to SCHEDULED.

Exchanges an HMAC-signed request for a short-lived Bearer token. See Authentication for the signing scheme.

A smoke-test endpoint that echoes the caller’s identity from the Bearer token. Useful to confirm the mint → bearer pipeline works.

Pool-based flight search. Requires scope search:read.

Re-checks a batch of pool offers by id. Requires scope fare:read. The whole call returns 200 OK; the partner inspects each entry’s status. Up to 100 ids per call.

current_price is the authoritative per-seat (1 adult) price — base + fare + per-seat taxes — computed by the same pricing engine as /search and order creation, in the session currency (the currency minted into the token), so re-price, search and the charged amount are directly comparable. A bare offer_id carries no trip context, so current_price is always the one-way price: for a leg of a round trip it excludes the airline’s global round-trip discount (if configured) that round-trip /search and the order apply. An offer with multiple fare frames quotes its cheapest frame (a "from" price); when none of the offer’s frames can currently be priced (e.g. no seat available), current_price is null. Each result is also enriched with fares: one entry per fare_frame_id carrying the marketed fare name, baggage allowance, and change/refund rules. Change/refund `amount_value`s are expressed in the session currency.

Returns an indicative per-passenger-type (ADT/CHD/INF) price breakdown and total for a single pool offer, using the same per-pax fares and taxes as the order flow (not a ratio estimate). Requires scope fare:read. The breakdown is denominated in the session currency.

offer_id and fare_frame_id come from a /search offer. For an offer taken from a round-trip search pass "round_trip": true — the breakdown then includes the airline’s global round-trip discount (if configured) and matches the per-leg /search total_price; without it the offer is priced one-way. The call returns 404 OFFER_NOT_AVAILABLE if the offer/fare frame is not priceable, 409 OFFER_SOLD_OUT if it is not available for the requested passengers, and 503 SERVICE_UNAVAILABLE on a downstream failure.

Returns the dates that have available flights for an origin/destination within a date range, each with the minimum sellable price, so a partner can render a price calendar. Requires scope search:read.

dates[].min_price is the engine total_price of the date’s cheapest sellable offer candidate for the requested passenger composition — base + fare + per-pax taxes with pax-type discounts applied, priced by the same engine as /search, in the session currency (currency echoes it). Guaranteed never lower than any /search total; in rare configurations (flights on one date carrying different pax-type discount groups) it may name a slightly pricier offer than /search’s minimum. The composition is set by the optional `adt/chd/inf query parameters (defaults 1/0/0); adt is 1..9, chd/inf are 0..9, inf must not exceed adt, and the total must not exceed 9 — the same rules the airline’s own IBE enforces. min_price is null when the date is available by quota but none of its offers can currently be priced for the party.

The range is bounded: outbound_date_from must not be after outbound_date_to, and the span must not exceed 62 days — otherwise the call returns 400 INVALID_REQUEST. A downstream availability-service failure returns 503 SERVICE_UNAVAILABLE.

Returns the origin/destination pairs available on the channel as a nested origin→destinations tree, enriched with airport and city names. Requires scope search:read. A downstream failure returns 503 SERVICE_UNAVAILABLE.

Returns the catalog of purchasable extra-service ancillaries (baggage, services) available for a flight, before any order exists — the pre-booking equivalent of the order-scoped List Ancillaries. Requires scope search:read. A downstream failure returns 503 SERVICE_UNAVAILABLE.

Prices are denominated in the partner session currency. Each entry carries the common fields (offer_id, offer_frame_id, category, name, price, max_per_pax) plus the fields specific to its category (omitted when not applicable).

Returns the full cabin map for a flight, before any order exists: the seat-selection price tiers (tiers — tier type, cabin, the currently-sellable seat numbers in the tier, price, and a render colour) plus a per-seat enumeration of the whole cabin (seats, DEL-2297). Requires scope search:read. Prices are denominated in the partner session currency.

seats[] semantics:

Lists the special assistance (SSR — wheelchair, blind or deaf passenger, infant bassinet, service animal, etc.) offered on every flight in flight_ids, before any order exists. Requires scope search:read. Special assistance is free of charge — there is no price, currency or quantity.

Pass all flights of the itinerary in one call: only options available on each of them are listed. Availability depends on the time left before departure, so an option can disappear between this call and Create Order. Select options per passenger in Create Order (ssrs).

Returns the machine-readable booking rules the partner should enforce client-side, so a booking form validates against the same source of truth the API does instead of hardcoding constants. The rules object is an extensible envelope: it will grow new named sections (and existing sections new fields) over time — clients MUST ignore unknown keys, and an absent section means "not published", never "no constraint". Breaking changes ship only under a new API version. Requires scope search:read.

The endpoint is flight-scoped: supply one flight_id (one-way) or two (round trip) — flight_id is required. It returns the passenger-composition rules (max_pax, adult_required, infant_per_adult); pax_types — the ADT/CHD/INF age boundaries resolved for the journey’s combined direction (any international leg makes the whole journey international, which can widen or narrow the child/infant bands; use them to validate passenger dates of birth, with age_reference naming the date the age is taken at — the outbound departure); and each flight’s special-quota ceilings in context.flights[].quotas.

Reserves seats on a pool offer for a configurable time-to-live, giving the partner time to collect passenger details before creating an order. Requires scope order:write.

For a round-trip (DEL-1710), also supply return_pool_offer_id (one of the chosen outbound offer’s valid_return_offer_ids from /search). Both legs are held under one hold_id and share the outbound fare_frame_id (the round-trip search prices them under one fare frame). The return offer is validated as a genuine reverse leg — it must fly the outbound’s destination back to its origin and leave at least the airline’s minimum connection time after the outbound arrives (the same min-time-between-routes rule the order step enforces, so a hold never succeeds for a pairing the order would reject); otherwise the hold is rejected with 400 INVALID_RETURN_PAIRING and nothing is reserved. If the return leg can’t be held the whole hold fails (nothing is reserved) and the return-leg outcome is returned. The resulting /orders call then books both legs as one round-trip order.

Creates an order from a previously obtained hold. For a round-trip hold the order covers both legs — total_amount is the whole trip: the sum of the per-leg /search prices, plus order-level fees if the airline configures them, and possibly a currency-rounding residual on non-domestic settlement currencies — as everywhere in this API. Requires scope order:write.

This endpoint is idempotent — callers MUST supply an Idempotency-Key header (UUIDv4 recommended). Repeating the call with the same key returns the original order instead of creating a duplicate.

Returns order details for a partner-owned order. Requires scope order:read. Partners can only read their own orders; an unknown or foreign order returns 404 ORDER_NOT_FOUND.

Returns the air ticket for a partner-owned order — the record locator (PNR) and per-passenger e-ticket numbers — so the passenger can check in and board. The ticket is issued by Farel as carrier. Requires scope order:read.

E-tickets exist only after the order has been paid and ticketed (see Confirm Wallet Payment). Before that the endpoint returns 409 TICKET_NOT_AVAILABLE. An unknown or foreign order returns 404 ORDER_NOT_FOUND. A passenger without a separate document (e.g. an infant) is still listed, with a null eticket_number.

Renders the passenger e-ticket (itinerary receipt) PDF for a paid and ticketed order — the same document served on the airline’s own channels, with per-airline branding. Requires scope order:read.

lang selects the document language per request (default en_US; supported: en_US, ru_RU, fr_FR, es_ES, pt_PT, ky_KG — anything else renders en_US, while the filename’s language tag echoes the requested locale; an unparseable value returns 400 INVALID_REQUEST). Gates are identical to Get Order Ticket: an unpaid/unticketed order returns 409 TICKET_NOT_AVAILABLE, an unknown or foreign order returns 404 ORDER_NOT_FOUND.

The response body is the PDF itself: Content-Type: application/pdf and Content-Disposition: attachment; filename*=UTF-8''…​ with a localized filename, e.g. Eticket AB12CD (en).pdf. Error responses remain JSON (DistributionErrorResponse).

Partners can check their passengers in online and hand out boarding passes, with the same check-in window and rules as the airline’s own website. The order must be paid and ticketed (the gate of Get Order Ticket). Every flight of the order is checked in separately.

The usual flow:

Returns, per flight of the order, the online check-in window and, per passenger, the check-in status and seat. Requires scope order:read.

check_in_window is one of OPEN, NOT_OPENED_YET, CLOSED, FLIGHT_CANCELED. Passenger status is one of NOT_CHECKED_IN, CHECKED_IN, BOARDED. seat_number is null until the passenger has a seat.

Failure cases: 404 ORDER_NOT_FOUND; refusal 200 TICKET_NOT_AVAILABLE.

Checks passengers in on one flight of the order and assigns each one a seat. Requires scope order:write.

Failure cases: 400 INVALID_REQUEST (empty passengers, a blank seat_number, or a repeated passenger_id), 404 ORDER_NOT_FOUND, 404 PASSENGER_NOT_ON_FLIGHT (also when flight_id is not a flight of the order); refusals 200 with TICKET_NOT_AVAILABLE, CHECK_IN_NOT_OPEN, CHECK_IN_CLOSED, FLIGHT_CANCELED, SEAT_UNAVAILABLE, SEAT_NOT_ELIGIBLE, PAID_SEAT_NOT_PURCHASED, PASSENGER_NOT_ELIGIBLE. A refusal checks no one in: the request applies to all its passengers or to none.

Returns one boarding pass per checked-in passenger on one flight of the order. barcode is the IATA BCBP (Bar Coded Boarding Pass) data string to render as a PDF417 barcode. Requires scope order:read.

Failure cases: 404 ORDER_NOT_FOUND, 404 FLIGHT_NOT_FOUND (the flight is not in the order); refusals 200 with TICKET_NOT_AVAILABLE, PASSENGER_NOT_CHECKED_IN, BOARDING_PASS_NOT_AVAILABLE.

Renders the boarding pass PDF of the checked-in passengers on one flight of the order — the same document the airline’s website issues, one page per passenger. Requires scope order:read.

The response body is the PDF itself: Content-Type: application/pdf and Content-Disposition: attachment with the filename boarding-pass-<order number>.pdf. Error responses and refusals remain JSON (DistributionErrorResponse).

Failure cases: 404 ORDER_NOT_FOUND, 404 FLIGHT_NOT_FOUND; refusals 200 (JSON) with TICKET_NOT_AVAILABLE, PASSENGER_NOT_CHECKED_IN.

Prices a single-leg, single-direction exchange of the FLIGHT items in items_to_replace onto a pool offer (pool_offer_id / fare_frame_id) and returns the extra amount (delta) and change penalty the customer would owe — WITHOUT committing the exchange and WITHOUT persisting anything (pricing runs in a rolled-back transaction). Requires scope order:read. Use it to preview an exchange before committing.

Pass the returned delta back as expected_delta when committing the exchange, so the commit is rejected if the price moved in between. A downgrade prices to a delta of 0 — the fare drop is forfeited, not refunded, and that lost amount is reported as forfeited_amount so you can show it to the passenger before they confirm. An involuntary exchange — the airline cancelled or rescheduled the flight — is free of penalty and delta: involuntary is true and free_reason names why (ALTERNATIVE_FLIGHT or INVOLUNTARY_FULL). valid_until is advisory; the commit re-checks the price regardless.

A malformed request — items_to_replace empty, listing the same item twice, or naming an item that is not on the order — returns 400 INVALID_REQUEST. An unknown or foreign order returns 404 ORDER_NOT_FOUND. An exchange the engine cannot make — multi-leg or multi-direction, exchanging only some passengers of a booking, ancillaries on the changing leg, special assistance on a changing or carried leg, past the change cut-off, and similar — returns 409 EXCHANGE_NOT_ELIGIBLE; a target offer that is sold out, no longer available, or over its subquota returns 409 OFFER_SOLD_OUT / OFFER_NOT_AVAILABLE / SUBQUOTA_EXCEEDED. All amounts are in the order’s currency, echoed as currency.

Commits the exchange previewed by Quote Exchange. Pass the quoted delta and penalty back as expected_delta and expected_penalty: if the live price no longer matches — because inventory or fares moved since the quote — the commit is rejected with 409 EXCHANGE_PRICE_CHANGED, and the partner should re-quote. Requires scope order:write. The Idempotency-Key header is required; repeating a commit with the same key replays the original result rather than exchanging twice — but while the original commit is still in flight, a repeat with the same key returns 409 IDEMPOTENCY_CONFLICT.

On success the exchange is committed and the new booking lands awaiting the delta payment. The response carries status (PENDING_PAYMENT while a delta invoice is outstanding, or COMMITTED when nothing is payable) and, when pending, the invoice_id, amount_to_pay (which may be 0), and payment_intent_id. Settle it with Settle Exchange Payment against that invoice_id — the exchange delta invoice is settled by that dedicated endpoint, not by the initial-purchase Confirm Wallet Payment. The same eligibility and availability rejections as Quote Exchange apply (EXCHANGE_NOT_ELIGIBLE, OFFER_SOLD_OUT, OFFER_NOT_AVAILABLE, SUBQUOTA_EXCEEDED).

Debits the partner wallet for the exchange delta invoice returned by Commit Exchange and finalizes the exchanged booking. invoice_id is the one from the commit response; payment_reference doubles as the idempotency key and is stored against the wallet transaction for reconciliation. A 0-amount delta is settled the same way. Requires scope order:write.

If the wallet is debited but ticketing cannot complete synchronously the response is 202 with status: TICKETING_DEFERRED and the PAYMENT_CAPTURED webhook finalizes the booking. In the rarer case where the wallet is debited but the exchange cannot be finalized and cannot be safely deferred, the response is 500 WALLET_SETTLEMENT_INCONSISTENT and the debit is flagged for reconciliation (the exchange is not activated). An insufficient wallet limit returns 402 INSUFFICIENT_WALLET_LIMIT; an already-settled or non-payable delta returns 409.

Cancels an exchange whose delta invoice has not been paid, restoring the original booking. invoice_id is the exchange delta invoice from the commit response. Requires scope order:write and a required Idempotency-Key header. A paid or already-cancelled exchange returns 409 EXCHANGE_NOT_CANCELLABLE; an unknown order or invoice returns 404.

Adds a lap infant to a paid order. The infant is priced on the flights the order’s first adult flies, and the call issues an invoice for it; the infant travels once that invoice is settled with Settle Infant Addition Payment. Requires scope order:write and a required Idempotency-Key header.

The body is the passenger object of Create Order with the same field names and validation. The passenger type is not sent: an added passenger is always an infant, and a date of birth that is not an infant’s on the departure date of the adult’s first flight returns 400 INVALID_REQUEST. seat_assignments, ancillary_offers and ssrs are rejected with 400 INVALID_REQUEST rather than silently dropped.

Settles an infant addition invoice from the partner wallet and issues the infant. invoice_id is the one returned by Add Infant, and only this endpoint settles it: Confirm Wallet Payment and Settle Exchange Payment answer 409 ORDER_NOT_PAYABLE for it, as this one does for their invoices. payment_reference doubles as the idempotency key of the wallet debit; sending it again after a successful settlement answers 409 ORDER_ALREADY_PAID. A free infant needs no settlement — its addition already answered COMMITTED. Requires scope order:write.

202 means the wallet was debited but issuing is still in flight; it completes on the payment webhook, and Get Order shows the infant’s pax segments as ISSUED once it does. A 500 WALLET_SETTLEMENT_INCONSISTENT means the wallet was debited and the addition could not be finalized — do not retry, contact support with order_id and invoice_id.

Failure cases: 400 INVALID_REQUEST (missing, blank or malformed payment_reference), 402 INSUFFICIENT_WALLET_LIMIT, 404 ORDER_NOT_FOUND, 409 ORDER_NOT_PAYABLE (the invoice is cancelled, expired, or not an infant addition awaiting payment), 502 WALLET_PAYMENT_FAILED.

Cancels an infant addition whose invoice has not been settled: the invoice is voided and the seat hold released. The infant’s own booking is closed, and the order returns to what it was before the addition. Requires scope order:write and a required Idempotency-Key header.

A settled or expired addition, or one on an order that is no longer ACTIVATED, returns 409 INFANT_ADDITION_NOT_CANCELLABLE; an invoice of the order that is not an infant addition — the purchase invoice, an exchange delta or an ancillary addition — returns 400 INVALID_REQUEST; an unknown order or invoice returns 404 ORDER_NOT_FOUND. Repeating the call with the same key on the same invoice returns 200. An Idempotency-Key already spent on another invoice of this order returns 409 IDEMPOTENCY_CONFLICT and cancels nothing. A key already spent on a different kind of operation, such as Add Infant, cannot be replayed here at all and answers 500 INTERNAL_ERROR without cancelling anything. Use a fresh key per operation; a reused one is never a safety net.

Returns a read-only refund quote for a partner-owned order — the net refundable amount, the penalty, and an informational gross fare / tax-and-charge / ancillary breakdown — without running the refund and without locking the order. Requires scope order:read. Use this to preview what a voluntary refund would return before committing to it.

refundable_amount is the authoritative total — the amount that would be credited to the partner — and penalty_amount is the withheld penalty. The fare_refund_amount, tax_and_charge_refund_amount, and offer_refund_amount fields are an informational gross breakdown of the refunded fare, tax-and-charge, and ancillary portions ONLY; they do not break out order-level fees or discounts and therefore do not necessarily sum to refundable_amount plus penalty_amount when the order carries fees or discounts.

v1 quotes the FULL order only; partial or offer-only scopes are planned as future work. An unknown or foreign order returns 404 ORDER_NOT_FOUND. An order with no PAID invoice to refund from is not refundable and returns 409 ORDER_NOT_REFUNDABLE. All amounts are expressed in the order’s currency.

The non_refundable_reason field carries a machine-readable cause when a refund is blocked by the departure time cutoff — currently the only value, TIME_LIMIT_ELAPSED — and is null otherwise. Beyond the invoice and booking checks above, the quote applies the SAME departure time cutoff as POST …​/refund: once the voluntary-refund window before departure has elapsed, the quote returns 200 with non_refundable_reason: "TIME_LIMIT_ELAPSED" and the amount fields still describing what WOULD have been refundable, instead of promising an amount that the refund would then reject with 409 ORDER_NOT_REFUNDABLE. It captures the time cutoff specifically, not every non-refundable state: an order with no PAID invoice is still rejected by the checks above with 409 ORDER_NOT_REFUNDABLE, while an already-refunded order returns a quote with refundable_amount of 0 and non_refundable_reason of null. Treat a positive refundable_amount together with non_refundable_reason == null as the go-ahead. Involuntary refunds (airline-driven cancel or reschedule) are not blocked by this cutoff.

Refunds a partner-owned order via the booking-refund engine. Requires scope order:write. By default the FULL order is refunded; supply pax_segment_ids to refund only those pax-segments (partial). The refund is ASYNCHRONOUS: the endpoint returns 200 immediately with a booking-derived refund status, and the partner’s wallet is credited automatically once farel-os-payments settles it — the partner is NOT credited synchronously and the response carries no credit-note or PSP refund reference (those surface on the wallet statement).

The Idempotency-Key header is required (for consistency with the other write endpoints) but is NOT currently used to replay a prior refund. A retry does not replay the original refund; instead, re-refunding already-refunded pax-segments is rejected by a segment-state guard with 409 ORDER_NOT_REFUNDABLE instead of being refunded again. A missing (or blank) Idempotency-Key header returns 400 INVALID_REQUEST. An unknown or foreign order returns 404 ORDER_NOT_FOUND; an order not in a refundable state returns 409 ORDER_NOT_REFUNDABLE. A broken internal invariant while refunding returns 500 INTERNAL_ERROR.

The returned status is a booking-derived refund status — exactly one of PROCESSING, REFUNDED, or PARTIALLY_REFUNDED (it is NOT the order-level OrderStatus and is never ACTIVATED/PAID). PROCESSING means the refund was accepted and settlement is still completing asynchronously; the booking moves to REFUNDED / PARTIALLY_REFUNDED once settled.

Confirms an externally-collected payment for a partner-owned order and settles it from the partner’s wallet. Requires scope order:write. The amount is taken server-side from the order’s invoice; the body carries only the PSP payment_reference (the unique payment id from the partner’s payment provider). The wallet is debited within its credit limit and the order is ticketed.

The payment_reference is the idempotency / dedup key: because a PSP payment id is unique per payment, replaying the same payment_reference does not double-debit or double-ticket (a replay after success returns 409 ORDER_ALREADY_PAID), and the value is stored against the wallet transaction so it can be matched back to the partner’s own PSP statement via GET /distribution/v1/wallet/transactions.

A 200 means the wallet was debited and the order is ticketed. A 202 means the wallet was debited but ticketing is still completing asynchronously — poll GET /distribution/v1/orders/{orderId} (which requires the order:read scope) for the final status. A missing, blank, or over-long payment_reference returns 400 INVALID_REQUEST in the standard distribution error envelope.

Errors: 400 INVALID_REQUEST (missing, blank, or over-long payment_reference), 402 INSUFFICIENT_WALLET_LIMIT (available limit below the invoice total; no debit, checked atomically by the wallet settlement service), 409 ORDER_ALREADY_PAID, 409 ORDER_NOT_PAYABLE (invoice not in a payable state, or the order is already activated — only the initial-purchase invoice is settled here), 404 ORDER_NOT_FOUND (unknown or foreign order), 502 WALLET_PAYMENT_FAILED (settlement service error), 500 WALLET_SETTLEMENT_INCONSISTENT (wallet debited but the order went terminal and cannot be ticketed — under reconciliation), 503 SERVICE_UNAVAILABLE (the partner-order ownership store was momentarily unreachable — a retriable infrastructure failure, distinct from a 404).

Lists the ancillaries (extra baggage, change-and-refund, other services) available for an order, together with those already selected, grouped by passenger and pax-segment. Requires scope ancillary:read. Seat selection is not included (separate endpoint, later milestone).

The orderId is resolved to its booking internally.

Three things this catalog does not tell you, each of which Add Ancillaries can still refuse on:

Buys ancillaries for one passenger segment of a paid order and issues an invoice for them. The ancillaries are provisioned once that invoice is settled from the partner wallet with Settle Ancillary Addition Payment; an unsettled invoice expires at payment_due_date and releases the inventory hold. Requires scope ancillary:write and an Idempotency-Key header.

Ancillaries are added only after the order is paid — an order still awaiting payment returns 409 ORDER_NOT_ACTIVATED. Services wanted before payment go into POST /orders (ancillary_offers) and are paid together with the flight.

Offer the frames from List Ancillaries for that pax segment: a frame the catalog does not list for it returns 409 OFFER_NOT_AVAILABLE — including an offer whose per-flight quota ran out, since the catalog stops listing it — and a quantity above the remaining per-passenger allowance returns 409 ANCILLARY_LIMIT_EXCEEDED. The price is the catalog price of the frame; the server computes the total itself, so no expected amount is sent.

Debits the partner wallet for an ancillary addition invoice and provisions the ancillaries. Requires scope ancillary:write.

Only this endpoint settles that invoice: Confirm Wallet Payment, Settle Exchange Payment and Settle Infant Addition Payment answer 409 ORDER_NOT_PAYABLE for it, as this one does for their invoices.

payment_reference is the partner’s own reference for the debit and doubles as the wallet idempotency key, so repeating the call for the same invoice with the same reference debits the wallet once. The key is derived from the reference together with the invoice’s payment intent, so the same reference sent for a different invoice is a different debit, not a replay.

Whether a rejected debit comes back as 402 INSUFFICIENT_WALLET_LIMIT or 502 WALLET_PAYMENT_FAILED depends on how the wallet words its rejection, so do not treat 402 as the only signal of an exhausted limit. In both cases no money moved and the addition is untouched: top up and call again, or cancel the addition.

A 202 means the wallet was debited but provisioning is still in flight; the ancillaries appear in List Ancillaries shortly. Do not retry a 202 — the money already moved. A 500 WALLET_SETTLEMENT_INCONSISTENT means the wallet was debited and the addition could not be activated; do not retry, contact support with the request_id.

Failure cases: 400 INVALID_REQUEST (malformed payment_reference), 402 INSUFFICIENT_WALLET_LIMIT, 404 ORDER_NOT_FOUND, 409 ORDER_ALREADY_PAID, 409 ORDER_NOT_PAYABLE (the invoice is not an ancillary addition awaiting payment), 500 WALLET_SETTLEMENT_INCONSISTENT, 502 WALLET_PAYMENT_FAILED.

Cancels an ancillary addition whose invoice has not been settled: the invoice is voided and the inventory hold released. The order returns to what it was before the addition. Requires scope ancillary:write and an Idempotency-Key header.

A settled or expired addition, or one on an order that is no longer ACTIVATED, returns 409 ANCILLARY_ADDITION_NOT_CANCELLABLE; an invoice of the order that is not an ancillary addition — the purchase invoice, an exchange delta or an infant addition — returns 400 INVALID_REQUEST; an unknown order or invoice returns 404 ORDER_NOT_FOUND. Repeating the call with the same key on the same invoice returns 200. An Idempotency-Key already spent on another invoice of this order returns 409 IDEMPOTENCY_CONFLICT and cancels nothing. A key already spent on a different kind of operation — an Add Ancillaries call, say — cannot be replayed here at all and answers 500 INTERNAL_ERROR without cancelling anything. Use a fresh key per operation; a reused one is never a safety net.

Lists the special-assistance options (SSR — wheelchair, blind/deaf passenger, infant bassinet, service animal, etc.) available for an order, together with those already selected, per pax-segment. Requires scope assistance:read. Special assistance is free of charge — there is no price, currency or quantity.

The response lists each pax-segment with its passenger_id (so options can be rendered/selected per traveler) and an ssr_not_available flag distinguishing a blocked segment from an empty catalog. applicable_pax_types lists which passenger types the SSR can be selected for; code is the IATA SSR code, type the internal enum value.

Special assistance sent in Create Order (ssrs) appears under selected as soon as the order is created, before payment. Until the order is paid available is informational only: Add Assistance returns 409 BOOKING_NOT_ACTIVATED.

Adds the partner-selected special assistance (SSR) to the pax-segments of an order, then returns the refreshed snapshot (same shape as List Assistance). Requires scope assistance:write.

This endpoint is idempotent when an Idempotency-Key header is supplied (optional but strongly recommended; UUIDv4 recommended). Repeating the call with the same key does not add the SSRs twice; it returns the booking’s current assistance snapshot. Without the header the add runs once with no replay protection.

Creates the partner’s wallet in the airline’s default currency, or returns the existing one. Idempotent — re-running returns the same wallet without creating a duplicate.

Sets the credit limit on the partner’s wallet, resolving (and, if necessary, creating) the wallet first. Idempotent — credit_limit is an absolute value, not a delta.

Returns the calling partner’s wallet balance. Requires scope wallet:read. The wallet is resolved from the authenticated session, so a partner only ever sees its own balance. available is the spendable remainder — current_balance + credit_limit (a debit lowers current_balance, which may be negative).

Returns a paginated statement of the calling partner’s wallet operations, most recent first. Requires scope wallet:read. Pagination is via page (0-based, default 0) and size (default 50, max 100). Invalid parameters — a negative page, or a size outside 1..100 — return 400 INVALID_REQUEST. A page past the end of the history is valid and returns 200 with an empty items list. total is the full (filtered) operation count.

For self-service reconciliation the statement can be narrowed with optional query parameters, combinable with each other and with pagination:

Each item carries order_id and payment_reference. order_id is populated only when you filter by order_id (every returned row then belongs to that order); it is null on the unfiltered statement — reconcile the unfiltered statement via the order_id filter and the intent_id. payment_reference carries the PSP reference supplied at payment (DEL-2054); it is null for operations without one (e.g. top-ups and refunds — take the reference from the order’s PAYMENT row in the same filtered view).