Guides · Servicing
Post-Booking Servicing
Add seats and extras, change flights, cancel and refund an existing order. Any order that is not cancelled, refunded or failed can be serviced. Service bookings only through these endpoints, never directly with the airline.
D-223Quote first, then confirm
Operations
| Operation | Endpoints |
|---|---|
| Add extras (bags, meals, assistance) | GET /v1/orders/{id}/services → POST /v1/orders/{id}/services |
| Airline schedule change | order.schedule_changed webhook, or GET /v1/orders/{id}?refresh=true |
| Cancel | POST /v1/orders/{id}/cancel → POST /v1/orders/{id}/cancel/confirm, or DELETE /v1/orders/{id} |
| Change flights | POST /v1/orders/{id}/reshop → POST /v1/orders/{id}/change/confirm |
| Choose seats | GET /v1/orders/{id}/seats → POST /v1/orders/{id}/seats |
| History | GET /v1/orders/{id}/history |
| Pay a held order | POST /v1/orders/{id}/commit |
| Refund | GET /v1/orders/{id}/refund-eligibility → POST /v1/orders/{id}/refund |
| Reprice the order | POST /v1/orders/{id}/quote |
Seats name segment_id, passenger_id and seat_id from the seat map; extras name ancillary_offer_id (the service_id) and passenger_id from the service list. Anything not on the list you read is 422 extra_not_priced. Add ?ssr=WCHR,UMNR to the service list for special service requests (SSRs). On a ticketed order include a payment; on a hold leave it out.
Changing flights
1
Find alternatives
POST /v1/orders/{id}/reshop with what should change: new_departure_date, new_return_date (RFC 3339, e.g. 2026-11-20T00:00:00Z), new_origin, new_destination. Returns { offers: [...] }.
2
Read the difference
Each offer's total_amount is the difference against the current order: positive is owed to the airline, negative is owed back.
3
Confirm
POST /v1/orders/{id}/change/confirm with { "offer_id": "…" }, plus a payment when the difference is positive. Returns the updated order.
Cancelling and refunding
- A hold that was never paid has nothing to refund (409 nothing_to_refund): cancel it instead.
- GET …/refund-eligibility returns eligible, refund_amount and penalty_amount. POST …/refund answers 202 and marks the order refunded; the airline returns the money to the original card.
- POST …/cancel is a quote and changes nothing: { quote_id, refund_amount, penalty_amount, valid_until }, with refund_amount already net of the penalty.
- POST …/cancel/confirm cancels and returns the order (200); DELETE /v1/orders/{id} does the same with a 204.
- To cancel only some flights, send segment_ids on both calls and pass the quote's quote_id as cancellation_quote_id. The order becomes partially_cancelled.
Idempotency and retries
- 409 order_busy or idempotency_key_in_flight: another write is still running. Retry after Retry-After with the same key.
- 502 with a *_outcome_unknown code: the request reached the airline but the answer was lost. Do not resend it; read GET /v1/orders/{id}?refresh=true. Until it is settled, payments, extras and changes on the order answer 409 with the same code.
- 503 airline_unreachable or ledger_unavailable: nothing was sent. Retry after Retry-After with the same key.
- Send an Idempotency-Key on every write that moves money: booking with a payment, paying, changing, cancelling, refunding, and seats or extras with a payment. Without it: 400 idempotency_key_required.
- Use one key per action and reuse it on every retry. A retry of a write that already succeeded returns its first answer with Idempotent-Replayed: true. The same key with a different body is 409 idempotency_key_reused.
Every code is listed in Errors. What a servicing operation costs is in Pricing.