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.

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. 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. 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 seat-selection price tiers for a flight (tier type, cabin, the seat numbers in the tier, price, and a render colour), before any order exists. Requires scope search:read. Prices are denominated in the partner session currency.

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. 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).

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; an order with multiple active bookings after an exchange returns 409 BOOKING_AMBIGUOUS. All amounts are expressed in the order’s currency.

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; an order with multiple active bookings after an exchange returns 409 BOOKING_AMBIGUOUS. 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. An order with multiple active bookings (post-exchange) returns 409 BOOKING_AMBIGUOUS.

Adds the partner-selected ancillaries to an order. Requires scope ancillary: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 ancillaries twice; it returns the result of the first call, re-read from the order’s current state. Without the header the add runs once with no replay protection.

Adding ancillaries produces a new additional order whose order_id is returned; that id is owned by the partner and can be used with Get Order. Each body pax_segment_id must belong to the URL orderId’s booking, otherwise `400 INVALID_REQUEST.

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.

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. payment_reference carries the PSP reference supplied at payment (DEL-2054); it is null for operations without one (e.g. top-ups). The settlement service does not yet propagate an order id onto each operation; reconcile the unfiltered statement via the order_id filter and the intent_id.