# Flights (/docs/products/flights)

## What you can sell [#what-you-can-sell]

Flight tickets for one-way, return and multi-city trips. You search a trip for a set of passengers, get itineraries with
the fares bookable on each, quote a fare (with optional seats and paid extras such as bags), and book it for named
passengers. Prices are for all passengers together.

This page covers what is specific to flights. Authentication, environments, idempotency, errors, webhooks and the order
envelope are shared by every product:
[Quickstart](/docs/quickstart), [Authentication](/docs/authentication), [Environments](/docs/environments),
[Idempotency](/docs/idempotency), [Errors](/docs/errors), [Webhooks](/docs/webhooks) and [Orders](/docs/orders).

<Callout type="warn">
Flights are not available in Sandbox yet. Sandbox supports airtime, eSIM, gift cards, hotels and utility. See
[Testing in Sandbox](#testing-in-sandbox).

The examples on this page send to `$OPENROAM_URL` with `$OPENROAM_API_KEY`: set them to the base URL and key of an
environment where flights are enabled for your account (see [Environments](/docs/environments)). In Production, an
order is a real booking for named passengers, charged to your wallet.
</Callout>

## The flow [#the-flow]

| Step | Route |
|---|---|
| Search itineraries and fares | [`POST /v1/flights/search`](/docs/api-reference/flights/search) |
| Read a fare's seat map (optional) | [`GET /v1/flights/offers/{publicId}/seat-map`](/docs/api-reference/flights/get-seat-map) |
| Quote a fare | [`POST /v1/flights/quote`](/docs/api-reference/flights/quote) |
| Book it | [`POST /v1/flights/order`](/docs/api-reference/flights/create-order) |

Differences from the other products:

- **Search is a POST with a JSON body**, because trips and passengers do not fit a query string. It takes no query
  parameters.
- **There is no browse list, one-item route or catalog.** An itinerary exists only in the search response that returned
  it. There is also no airport or city lookup: send three-letter IATA airport or city codes.
- **Offers expire.** A fare's `publicId` (`flight_...`) is accepted until `details.expiresAt`. A fare that has already
  expired is not listed.
- **Quote returns a new `publicId`** that keeps the quoted price. A quote charges nothing.
- **A price cap protects the order.** See [Price cap at order](#price-cap-at-order).

Every route needs your partner key and flights enabled for your account. Only `order` also needs the `manage`
permission and an `Idempotency-Key` header.

## Search [#search]

```bash
curl -X POST "$OPENROAM_URL/v1/flights/search" \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "slices": [
      { "origin": "LHR", "destination": "JFK", "departureDate": "2027-03-12" },
      { "origin": "JFK", "destination": "LHR", "departureDate": "2027-03-19" }
    ],
    "passengers": [ { "type": "adult" }, { "type": "child", "age": 7 } ],
    "cabinClass": "economy",
    "filters": { "maxStops": 1, "refundableOnly": false, "maxPrice": 1500 },
    "page": 1,
    "limit": 10
  }'
```

| Field | Required | Rules |
|---|---|---|
| `slices` | yes | One per flight of the trip: one for one-way, two for a return, more for multi-city. Each has `origin` and `destination` (IATA airport or city codes) and `departureDate` (`yyyy-MM-dd`, the local date, today or later at the departure airport). |
| `passengers` | yes | One entry per traveller, with at least one `adult`. `type` is `adult`, `child`, `infantWithSeat` or `infantWithoutSeat`. `age` (0 to 17, on the travel date) is required for children and infants. |
| `cabinClass` | no | `economy`, `premiumEconomy`, `business` or `first`. |
| `filters` | no | See below. |
| `page`, `limit` | no | `page` starts at 1 (default 1). `limit` is 1 to 100 (default 10). They page itineraries, not fares. |
| `currency` | no | Three letters. Defaults to your API key's currency. |

Filters:

| Filter | Meaning |
|---|---|
| `maxStops` | At most this many connections in total. Use 0 for direct flights only. |
| `preferredAirlines` | Two-letter IATA airline codes. Keeps itineraries sold, marketed or flown by at least one of them. |
| `excludedAirlines` | Two-letter IATA airline codes. Drops itineraries sold, marketed or flown by any of them. |
| `refundableOnly` | When `true`, keeps only fares whose `details.terms.cancellation.type` is not `nonRefundable`. |
| `maxPrice` | Keeps fares whose price for all passengers is at most this number, in the search currency. |

Every filter you send must match. Every object of the body rejects an unknown member with `400 / 10001` at its JSON
path, for example `$.filters.minPrice`.

### Response [#response]

An item is one itinerary: the same flights sold by the same airline. The fares bookable on it are its `offers`,
cheapest first. Items are ordered by their cheapest fare.

```json
{
  "items": [
    {
      "id": "itin_9f1c2a7d3e4b5c6d7e8f9a0b1c2d3e4f",
      "name": "LHR ⇄ JFK · 12–19 Mar · Example Air",
      "countryCode": "US",
      "category": null,
      "logoUrl": "https://cdn.example.com/airlines/EX.png",
      "description": null,
      "offers": [
        {
          "publicId": "flight_example1234567890abcdefgh",
          "name": "Economy Basic, Non-refundable",
          "description": null,
          "price": { "amount": 1184.20, "currency": "USD" },
          "details": {
            "expiresAt": "2027-02-01T10:30:00Z",
            "cabinClass": "economy",
            "fare": { "fareBasisCode": "OXZ0RO", "brandName": "Basic", "fareFamily": "Economy Basic", "validatingCarrier": "EX" },
            "terms": {
              "payment": { "type": "payNow", "dueNow": { "amount": 1184.20, "currency": "USD" }, "dueLater": null, "dueLaterAt": null },
              "cancellation": { "type": "nonRefundable", "freeUntil": null, "freeUntilLocalTime": null, "timezone": "Europe/London", "schedule": [], "fee": null },
              "changes": { "allowed": true, "fee": null }
            },
            "includedBaggage": [ { "type": "carryOn", "quantity": 1, "weightKg": null, "description": null } ],
            "priceBreakdown": { "base": { "amount": 980.00, "currency": "USD" }, "tax": { "amount": 204.20, "currency": "USD" } },
            "offerPassengers": [
              { "passengerIndex": 1, "type": "adult", "age": null, "fareType": null, "includedBaggage": [], "availableServices": [] },
              { "passengerIndex": 2, "type": "child", "age": 7, "fareType": null, "includedBaggage": [], "availableServices": [] }
            ],
            "availableServices": [],
            "identityDocumentsRequired": true,
            "supportedDocumentTypes": ["passport"]
          }
        }
      ],
      "details": {
        "owner": { "iataCode": "EX", "name": "Example Air", "logoUrl": "https://cdn.example.com/airlines/EX.png" },
        "slices": [
          {
            "origin": { "iataCode": "LHR", "name": "Heathrow", "city": "London", "countryCode": "GB", "timezone": "Europe/London" },
            "destination": { "iataCode": "JFK", "name": "Kennedy International", "city": "New York", "countryCode": "US", "timezone": "America/New_York" },
            "departureAt": "2027-03-12T08:30:00Z", "departureLocalTime": "2027-03-12T08:30:00",
            "arrivalAt": "2027-03-12T16:20:00Z", "arrivalLocalTime": "2027-03-12T12:20:00",
            "durationMinutes": 470, "stops": 0,
            "segments": [ { "marketingFlightNumber": "117", "isCodeshare": false, "...": "..." } ]
          }
        ],
        "totalDurationMinutes": 905,
        "totalStops": 0,
        "totalEmissionsKg": 612
      }
    }
  ],
  "pagination": { "currentCount": 10, "totalCount": 37, "skip": 0, "limit": 10, "hasMore": true, "page": 1, "totalPages": 4 }
}
```

Points to know:

- The itinerary `id` (`itin_...`) names the itinerary within this response only. It is new on every search and cannot be
  ordered: quote, order and the seat map treat it as an unknown offer (`400 / 11004`). Use it only as a UI key.
- Quote and order a fare's `publicId`. It belongs to your partner key and expires at `details.expiresAt`.
- An offer's `name` is the brand after its cabin, followed by its cancellation terms: `, Free cancellation` only for a
  `fullyRefundable` fare, `, Non-refundable` for `nonRefundable`, and nothing for `partiallyRefundable`.
- `price` is the indicative price for all passengers in the search currency. The quote confirms it.
- Cabin, baggage and fare basis can differ between fares on the same flights, so they are on each offer. `details.segments`
  gives cabin and baggage per segment.
- `identityDocumentsRequired` says whether every passenger needs an identity document for this fare, and
  `supportedDocumentTypes` lists the types the airline takes (`passport`, `taxId`, `knownTravelerNumber`,
  `passengerRedressNumber`).
- `offerPassengers[].passengerIndex` (from 1) is the position you use for each passenger in the order inputs.
- `availableServices` is empty in search. Quote the fare to list paid extras.
- A fare whose type of cancellation terms is not sold to you is not listed, and quote and order refuse it with
  `409 / 11003`.

Each page runs a new search, so itineraries and prices can change between pages. Only the fares on the returned page get a
`publicId`. `items` is empty when no fare matches, when `page` is past the last page, and also when the airline could not
be searched at that moment. All three answer `200`, so search again before telling a customer there is no flight.

### Times and time zones [#times-and-time-zones]

Every flight time (slices, segments and stops) is a UTC instant ending in `Z`. Each airport carries its IANA `timezone`,
and each flight time has the clock of its airport beside it for display: `departureLocalTime` in the origin's zone and
`arrivalLocalTime` in the destination's. A clock is written `yyyy-MM-ddTHH:mm:ss` with no zone. Compute and compare with
the UTC instants. A clock is null when its airport's zone is unknown. In `details.terms.cancellation`, `timezone` is the
zone of the first departure airport, and `freeUntil`, each step's `from` and the matching `...LocalTime` fields follow
the same rule.

## Quote and order [#quote-and-order]

Quote and order take the same body. A quote may leave `inputs` out and then prices the fare alone; an order needs
`inputs` on every item.

```json
{
  "currency": "USD",
  "referenceId": "partner-trip-7",
  "items": [
    {
      "publicId": "flight_example1234567890abcdefgh",
      "quantity": 1,
      "inputs": {
        "passengers": [
          {
            "passengerIndex": 1, "title": "mr", "givenName": "Tom", "familyName": "Lee", "gender": "m",
            "bornOn": "1988-04-02", "email": "tom@example.com", "phoneNumber": "+447700900123",
            "identityDocuments": [ { "type": "passport", "uniqueIdentifier": "000000001", "issuingCountryCode": "GB", "expiresOn": "2031-06-30" } ],
            "selectedSeats": [ { "sliceIndex": 1, "segmentIndex": 1, "seatDesignator": "32A" } ]
          },
          {
            "passengerIndex": 2, "title": "ms", "givenName": "Mia", "familyName": "Lee", "gender": "f",
            "bornOn": "2019-03-14", "email": "tom@example.com", "phoneNumber": "+447700900123",
            "identityDocuments": [ { "type": "passport", "uniqueIdentifier": "000000002", "issuingCountryCode": "GB", "expiresOn": "2030-01-31" } ]
          }
        ],
        "selectedServices": [ { "id": "flight_service1234567890abcdefg", "quantity": 1 } ],
        "maxPrice": { "amount": 1250.00, "currency": "USD" }
      }
    }
  ]
}
```

- `items` holds 1 to 5 items. `quantity` must be 1: an item books one fare for all its passengers.
- `publicId` is a fare's id from search, or one a quote returned (the item's own or a fare option's).
- `currency` defaults to your API key's currency. `referenceId` is your own reference, unique per partner, at most 128
  characters.

### Product inputs [#product-inputs]

Positions (`passengerIndex`, `sliceIndex`, `segmentIndex`) are 1-based.

| Input | Required | Meaning |
|---|---|---|
| `passengers` | yes (order) | Every passenger of the fare exactly once, in `passengerIndex` order 1 to N. |
| `passengers[].title` | yes | For example `mr`, `ms` or `mrs`. |
| `passengers[].givenName`, `familyName` | yes | As on the travel document. |
| `passengers[].gender` | yes | `m` or `f`, as on the travel document. |
| `passengers[].bornOn` | yes | Date of birth, `yyyy-MM-dd`. |
| `passengers[].email` | yes | The passenger's email address. |
| `passengers[].phoneNumber` | yes | International format with a leading `+`, for example `+442080160509`. |
| `passengers[].identityDocuments` | when the fare's `identityDocumentsRequired` is `true` | At most one document. When required, every passenger needs a passport. Otherwise a document is optional and of a type in `supportedDocumentTypes`. Each has `type`, `uniqueIdentifier` (the number as printed), `issuingCountryCode` (ISO 3166-1 alpha-2) and `expiresOn`. |
| `passengers[].selectedSeats` | no | Seats from the seat map, at most one per segment: `sliceIndex`, `segmentIndex` and `seatDesignator` (for example `14B`). |
| `selectedServices` | no | Paid extras from the quote item's `details.availableServices`, such as bags. Send the service `id` (or `type` of `baggage` or `meal` with positions), and optionally `passengerIndex`, `sliceIndex`, `segmentIndex` and `quantity` (default 1, at most the service's `maxQuantity`). |
| `maxPrice` | no | The price cap. See below. |

Flights have no monetary value, so `inputs.value` is not accepted. An invalid input gives `400 / 10001` at its path
under `items[i].inputs`, for example `items[0].inputs.passengers[0].email`. Passengers out of `passengerIndex` order give
`400 / 10001` at `items[i].inputs.passengers`.

### The quote response [#the-quote-response]

```json
{
  "currency": "USD",
  "items": [
    {
      "publicId": "flight_example2234567890abcdefgh",
      "quantity": 1,
      "name": "LHR ⇄ JFK · 12–19 Mar · Economy Basic, Non-refundable",
      "price": { "amount": 1214.20, "currency": "USD" },
      "details": {
        "expiresAt": "2027-02-01T10:30:00Z",
        "quotedAt": "2027-02-01T10:05:12Z",
        "hasSeatMaps": true,
        "terms": { "payment": { "...": "..." }, "cancellation": { "...": "..." }, "changes": { "...": "..." } },
        "includedBaggage": [ { "type": "carryOn", "quantity": 1, "weightKg": null, "description": null } ],
        "priceBreakdown": { "base": { "amount": 980.00, "currency": "USD" }, "tax": { "amount": 204.20, "currency": "USD" } },
        "availableServices": [
          {
            "id": "flight_service1234567890abcdefg", "type": "baggage", "price": { "amount": 30.00, "currency": "USD" },
            "passengerIndexes": [1], "segments": [ { "sliceIndex": 1, "segmentIndex": 1 } ], "maxQuantity": 2,
            "baggage": { "type": "checked", "maximumWeightKg": 23 }
          }
        ],
        "fareOptions": [
          { "publicId": "flight_example3234567890abcdefgh", "name": "Economy Standard", "price": { "amount": 1290.00, "currency": "USD" }, "details": { "...": "the fare's details, as in search" } }
        ]
      }
    }
  ],
  "total": { "amount": 1214.20, "currency": "USD" }
}
```

- `price` is what the order charges now for all passengers: the fare with its taxes, plus the paid extras in `inputs`
  when you send them. In the example the fare costs 1184.20 USD and the bag 30.00 USD.
- The new `publicId` keeps the fare's price as the cap of an order without `maxPrice`. Order it before `details.expiresAt`.
- `terms` are the terms you are buying, on the item's price.
- `hasSeatMaps` says whether the fare offers seats to choose.
- `availableServices` lists paid extras. A service `id` expires with the item's `publicId`.
- `fareOptions` lists the other fares on the same flights sold by the same airline, cheapest first. Quote or order a
  fare option's `publicId` to switch fare.

### Price cap at order [#price-cap-at-order]

`inputs.maxPrice` is `{ amount, currency }`: the highest price you accept for the item, the fare plus its paid extras, in
the order currency. Before payment, the order checks the price again:

- With `maxPrice`, a higher current price gives `409 / 11002` at `items[i].inputs.maxPrice`, on the quote and on the order.
- Without `maxPrice`, an order is capped at the price returned with the `publicId`, by search or quote. A fare that costs
  more now gives `409 / 11002` at `items[i]`. Paid extras are charged at their current prices, so an order can add bags
  that the price did not include. Send `maxPrice` to cap the extras as well.
- That price is in the currency the `publicId` was returned in, so an order in another currency without `maxPrice` gives
  `400 / 11005` at `items[i]`. Search or quote in the order currency, or send `maxPrice`.
- A `maxPrice` in another currency than the order gives `400 / 10001` at `items[i].inputs.maxPrice.currency`
  (`CURRENCY_MISMATCH`).
- Nothing is created, charged or booked when these checks refuse an order. A lower price is charged as it is.

A `publicId` keeps the price and currency it was returned with. After `409 / 11002`, quote again and order with the
new `publicId`, or send a `maxPrice` you accept. Ordering the same `publicId` again without `maxPrice` is refused again
while the fare costs more.

### Place the order [#place-the-order]

In Production this books the flight and charges your wallet.

```bash
curl -X POST "$OPENROAM_URL/v1/flights/order" \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Idempotency-Key: 2f6a9d41-7c3b-4b8e-a1d0-5e9f3c7b2a10" \
  -H "Content-Type: application/json" \
  -d @order.json
```

Follow the booking with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id) or the
[`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) webhook.

## Seat map [#seat-map]

[`GET /v1/flights/offers/{publicId}/seat-map`](/docs/api-reference/flights/get-seat-map) reads the current seat map of a
fare each time, so seats can change between calls. Use a fare's `publicId` from search or quote. The response is
`{ isSupported, segments, warnings }`.

- A segment is known by its 1-based `sliceIndex` and `segmentIndex` in the itinerary's `details.slices[].segments[]`.
  A segment the airline has no seat map for is left out.
- Each seat lists the passengers who can take it in `availableFor`, as `{ passengerIndex, price }`. Prices are in your API
  key's currency.
- Send a chosen seat in the order inputs as `passengers[].selectedSeats[]`. The order reads the seat map again and
  refuses a seat that is no longer offered to that passenger.

## Booking terms [#booking-terms]

Every fare, quote item and purchased booking states its terms in `details.terms`, with the same shape as hotels:
`{ payment, cancellation, changes }`. Money is in the response currency and includes OpenRoam's fees.

- **Payment.** A flight is always `payNow`: `dueNow` is the price, and `dueLater` is null.
- **Cancellation.** `cancellation.type` comes from the fare's refund rule before departure: `fullyRefundable` (a full refund
  until `freeUntil`, the first departure in UTC), `partiallyRefundable` or `nonRefundable`. `schedule` lists
  `{ from, fromLocalTime, refund, penalty }` steps from now and from departure. After the first departure, cancelling keeps
  everything. `fee` is OpenRoam's cancellation fee, already included in every penalty. A refund that the fare allows
  without a stated penalty promises nothing, so it reads `nonRefundable`.
- **Changes.** `changes.allowed` follows the airline's change rule before departure, and `changes.fee` is OpenRoam's fee
  per change, or null.
- The terms on a booked item never change afterwards.

## What the order item contains [#what-the-order-item-contains]

Read it with [`GET /v1/order-items/{id}`](/docs/api-reference/order-items/get-by-id) or in `items` of
`GET /v1/orders/{id}`.

```json
{
  "id": "019a2b5c-4d7e-7f10-8a2b-3c4d5e6f7081",
  "orderId": "019a2b5c-4d6a-7c33-9e15-7f2a8b4c6d10",
  "productType": "flight",
  "price": { "amount": 1214.20, "currency": "USD" },
  "purchasedProduct": {
    "name": "LHR ⇄ JFK · 12–19 Mar · Economy Basic, Non-refundable",
    "countryCode": "US",
    "logoUrl": "https://cdn.example.com/airlines/EX.png",
    "inputs": {
      "passengers": [
        {
          "passengerIndex": 1, "title": "mr", "givenName": "Tom", "familyName": "Lee", "gender": "m", "bornOn": "1988-04-02",
          "email": "t***@example.com", "phoneNumber": "+44***0123",
          "identityDocuments": [ { "type": "passport", "uniqueIdentifier": "***0001", "issuingCountryCode": "GB", "expiresOn": "2031-06-30" } ],
          "selectedSeats": [ { "sliceIndex": 1, "segmentIndex": 1, "seatDesignator": "32A" } ]
        }
      ],
      "selectedServices": [ { "id": null, "type": "baggage", "passengerIndex": 1, "sliceIndex": 1, "segmentIndex": 1, "quantity": 1 } ]
    },
    "details": {
      "owner": { "iataCode": "EX", "name": "Example Air", "logoUrl": "https://cdn.example.com/airlines/EX.png" },
      "slices": [ { "...": "the flights bought, as in search" } ],
      "cabinClass": "economy",
      "terms": { "payment": { "...": "..." }, "cancellation": { "...": "..." }, "changes": { "...": "..." } },
      "includedBaggage": [ { "type": "carryOn", "quantity": 1, "weightKg": null, "description": null } ],
      "selectedServices": [ { "type": "baggage", "label": "1 × 23 kg", "passengerIndex": 1, "sliceIndex": 1, "segmentIndex": 1, "quantity": 1 } ],
      "priceLines": [
        { "description": "Base fare", "amount": { "amount": 980.00, "currency": "USD" }, "quantity": 1, "serviceType": null, "category": "fare" },
        { "description": "Taxes", "amount": { "amount": 204.20, "currency": "USD" }, "quantity": 1, "serviceType": null, "category": "taxes" },
        { "description": "Checked bag", "amount": { "amount": 30.00, "currency": "USD" }, "quantity": 1, "serviceType": "baggage", "category": "selectedService" }
      ],
      "totalDurationMinutes": 905,
      "totalStops": 0
    }
  },
  "fulfillment": {
    "status": "fulfilled",
    "result": {
      "details": {
        "bookingStatus": "confirmed",
        "ticketDocuments": [ { "type": "electronicTicket", "uniqueIdentifier": "0000000000001" } ],
        "booking": { "slices": [], "cabinClass": "economy", "passengers": [], "terms": {}, "includedBaggage": [], "selectedServices": [], "totalDurationMinutes": 905, "totalStops": 0 }
      }
    },
    "failure": null
  },
  "actions": {
    "amendment": { "availability": "available", "reason": null },
    "cancellation": { "availability": "available", "reason": null },
    "update": { "availability": "notAvailable", "reason": null }
  },
  "createdAt": "2027-02-01T10:31:07.214Z",
  "effectivePaidAmount": { "amount": 1214.20, "currency": "USD" }
}
```

`purchasedProduct` is what was bought and does not change after purchase.

- `inputs` echoes the passengers and extras as applied. Names, titles, gender and date of birth read as sent. `email` and
  `phoneNumber` are masked (`t***@example.com`, `+44***0123`). A document's `uniqueIdentifier` is masked to `***` plus
  its last four characters. The `maxPrice` cap is not echoed.
- `details` holds the flights as bought (`slices`, with each segment's cabin and baggage), the cabin, the `terms` you
  bought, included baggage, the extras bought with a readable `label` such as `1 × 23 kg`, and `priceLines`. The price
  lines add up to the item's `price`; if rounding leaves a difference, one extra `Rounding adjustment` line carries it.

`fulfillment.result.details` is the booking's facts:

| Field | Meaning |
|---|---|
| `bookingStatus` | `confirmed`, `pending`, `cancelled` or `failed`. |
| `ticketDocuments` | The ticket documents issued, each `{ type, uniqueIdentifier }`. `type` is `electronicTicket`, `electronicMiscellaneousDocumentAssociated`, `electronicMiscellaneousDocumentStandalone` or `other`, and `uniqueIdentifier` is the document number, for example the e-ticket number. |
| `booking` | What is booked now: `slices`, `cabinClass`, `passengers`, `terms`, `includedBaggage`, `selectedServices`, `totalDurationMinutes` and `totalStops`. |

`booking` reads as the purchased product until a committed amendment changes it; then it has the flights, passengers and
extras booked now. Show "your trip" from `booking`, and what was paid for from `purchasedProduct`. The booking record
keeps no identity documents, so each passenger in `booking` has an empty `identityDocuments`. Changes the airline makes to
the schedule by itself are not processed yet.

The `order.fulfillment.updated` webhook is sent when the item's fulfillment changes. An amendment sends no webhook, so
read the order to see the changed `booking`.

## After purchase [#after-purchase]

These calls are shared by every product; see [Orders](/docs/orders).

- **Cancellation preview.** [`GET /v1/order-items/{id}/cancellation-preview`](/docs/api-reference/order-items/get-cancellation-preview)
  returns `penaltyAmount`, `cancellationFee`, `refundAmount`, `isRefundable`, `appliedPenalties` and `checkInDate`
  (always null for a flight, which has no check-in), in the order currency. It changes nothing.
- **Cancel.** [`POST /v1/order-items/{id}/cancel`](/docs/api-reference/order-items/cancel) takes
  `{ "reason": "requestedByCustomer" }` (or `duplicate` or `fraudulent`), needs the `manage` permission and an
  `Idempotency-Key`, and refunds what the fare's rules and OpenRoam's cancellation fee leave. The
  [`order-item.refunded`](/docs/api-reference/webhooks/order-item-refunded) webhook reports the refund. A fee that takes
  the whole refund still cancels the item with a refund of 0.
- **Fares that cannot be cancelled.** A non-refundable fare that would refund nothing cannot be cancelled: the preview
  answers `isRefundable: false` and cancel answers `400 / 10001`. A refundable fare can always be cancelled, even when
  nothing comes back. When a cancellation would be refunded as a voucher or airline credit, or its refund has not been
  paid yet, both calls answer `400 / 10001` and nothing is cancelled.
- **Airline unavailable.** When the airline cannot answer while pricing a cancellation (an error, a timeout or a rate
  limit), the preview, and cancel before any refund exists, answer `503 / 10007`. Nothing is cancelled: retry later.
- **Whole trip.** [`GET /v1/orders/{id}/cancellation-preview`](/docs/api-reference/orders/get-cancellation-preview)
  previews every item of an order in one call. A flight that cannot be cancelled is listed as `notCancellable` with the
  reason `notAllowed`. If the airline cannot answer, the whole call fails with `503 / 10007`.
- **Amendments.** Changes go through
  [`POST /v1/order-items/{id}/amendments/quote`](/docs/api-reference/order-items/quote-amendment) and then
  [`POST /v1/order-items/{id}/amendments/confirm`](/docs/api-reference/order-items/confirm-amendment), the same two-step
  flow as hotels. The quote returns `amendmentRequestId`, `expiresAt` and `options`, each `{ id, amountToPay, amountToRefund, amendmentFee }`, and nothing is charged until you confirm. OpenRoam's change fee, when the item's terms
  have one, is already included in each option's amounts. A committed amendment shows in
  `fulfillment.result.details.booking`. List amendments with
  [`GET /v1/order-items/{id}/amendments`](/docs/api-reference/order-items/get-amendments).
- **Update.** `POST /v1/order-items/{id}/update` is not supported for flights (`422 / 18004`). Use amendments.

## Testing in Sandbox [#testing-in-sandbox]

Flights are not available in Sandbox yet. Sandbox supports airtime, eSIM, gift cards, hotels and utility, and products
it does not support stay unavailable. The `OpenRoam-Sandbox-Scenario` header (`success`, `fulfillment.rejected`,
`fulfillment.pending`, `fulfillment.late_success` and `fulfillment.late_rejected`) works only on the order endpoints of
those products, not on flights. Build and test your flight integration against the request and response shapes on this
page, and use [Environments](/docs/environments) to see what each environment covers.

## Errors to handle [#errors-to-handle]

Shared error handling is in [Errors](/docs/errors). Flight specific cases:

| Status / code | Reason | Path | When and what to do |
|---|---|---|---|
| `400 / 10001` | `INVALID_VALUE` | the field, for example `slices[0].departureDate` | An invalid search field: no slice, an origin or destination that is not three letters, a past departure date, no adult, a child or infant without an age from 0 to 17, `limit` outside 1 to 100. |
| `400 / 10001` | `INVALID_VALUE` | the JSON path | An unknown member anywhere in the body, such as `$.maxResults` or `$.items[0].inputs.value`. |
| `400 / 10001` | `UNSUPPORTED_FIELD` | the parameter | A query parameter on search. |
| `400 / 10001` | `REQUIRED` | `items[i].inputs` | An order item without `inputs`. |
| `400 / 10001` | various | `items[i].inputs...` | An invalid passenger, document, seat or service input, at its path. |
| `400 / 10001` | `NOT_SUPPORTED` | `currency` | A currency OpenRoam does not support. |
| `400 / 11004` | `EXPIRED_OR_INVALID` | `items[i]` | An unknown, expired or foreign `publicId`, an itinerary `id` (`itin_...`), a service `id`, another product's offer, or a `publicId` that keeps no price. Search or quote again. On the seat map the error has no `details`. |
| `409 / 11002` | `PRICE_CHANGED` | `items[i].inputs.maxPrice` or `items[i]` | The price is above your `maxPrice`, or above the price returned with the `publicId`. Quote again, or send a `maxPrice` you accept. |
| `400 / 11005` | `CURRENCY_MISMATCH` | `items[i]` | An order without `maxPrice` in another currency than the price returned with the `publicId`. |
| `409 / 11003` | `UNAVAILABLE` | `items[i]` | The airline no longer sells the offer. |
| `400 / 10001` | none | none | Any other airline failure while pricing the fare. |
| `403 / 10003` | `SERVICE_NOT_ENABLED` | `service` | Flights are not enabled for your account. |
| `503 / 10007` | none | none | The airline cannot answer a cancellation preview or cancel. Retry later. |
| `409 / 18003` | `IN_PROGRESS` or `NOT_AVAILABLE` | `id` | An amendment cannot be quoted or confirmed now. |
| `422 / 18004` | none | none | `update` is not supported for flights. |

A failing request orders and charges nothing.