Skip to Content
OpenRoam Docs
Flights

Order flights

Places and pays for flight bookings, one fare per item.

POST
/v1/flights/order

Places and pays for flight bookings, one fare per item.

Takes the same body as quote, with inputs required. Requires an Idempotency-Key header (a new UUID per purchase) and an API key with order-manage permission. Repeating the same request with the same key returns the original order; while the first request is still running the response is 409 / 12002 with Retry-After, after which you send the same request again. The order is paid from your wallet balance and ticketing completes asynchronously: track it with GET /orders/{id} or the order.fulfillment.updated webhook.

publicId is a fare's publicId from search, or one that a quote returned. inputs.passengers lists every passenger of the fare exactly once, in passengerIndex order 1 to N, optionally with seats in selectedSeats; paid baggage and other services go in inputs.selectedServices. Seats and services are checked against the airline's current offer and seat map, and their prices are added to the item's price.

Each item is priced again with the airline before payment, and the price is capped. With the optional inputs.maxPrice, in the order currency, a higher price for the item (the fare with its paid extras) gives 409 / 11002 at items[i].inputs.maxPrice. Without it, the fare may not cost more than the price returned with the publicId (409 / 11002 at items[i]), and the order must be in the currency of that price (400 / 11005 at items[i]). A publicId keeps that price: after 409 / 11002, quote again and order with the publicId the quote returns, or send inputs.maxPrice.

Each item is checked completely before the next one, and the first failure names its item: an invalid input or missing inputs gives 400 / 10001 at its path under items[i], for example items[0].inputs.passengers[0].email; an unknown, expired or another partner's publicId 400 / 11004 at items[i]; an offer the airline no longer sells 409 / 11003 at items[i]. A wallet charge that fails gives 402 / 16000, with details[0] naming wallet and INSUFFICIENT_BALANCE or WALLET_BLOCKED; send the same request with the same key after a top-up. Nothing is created or charged when the order is refused.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Header Parameters

Idempotency-Key*string

UUID idempotency key for safe retries of this operation.

Formatuuid

Request Body

  1. body

The body B2B flight quote and order both take.

currency?|

Order currency, three letters in either case; the API key's currency when omitted. An unsupported code gives 400 / 10001 at currency, reason NOT_SUPPORTED, before any item is checked.

referenceId?|

Optional partner order reference, unique per partner, at most 128 characters without leading or trailing spaces. A quote validates it and ignores it.

items*array<>

1 to 5 items, each one fare for its passengers.

Response Body

OK

  1. response

The current state of an order.

id*string

Order id.

Formatuuid
origin*

Where the order was created.

status*string

Current order status: paymentPending, processing, completed, partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.

Value in"paymentPending""processing""completed""partiallyFulfilled""fulfillmentFailed""partiallyRefunded""refunded""cancelled"
total*

What was charged for the order, in the order's currency, before refunds: the item prices plus completed amendment charges, less completed amendment credits.

refunded*

What completed item refunds returned, in the order's currency; zero when nothing was returned. You paid total minus refunded, the sum of the items' effectivePaidAmount.

payment?|

The latest payment attempt; null when none was made.

items*array<>

The order items, one per unit bought.

timeline*array<>

Every status the order has had, oldest first, each once per stretch.

createdAt*string

When the order was created (UTC).

Formatdate-time
updatedAt*string

When anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.

Formatdate-time
fulfillmentVersion*integer

Increases with every fulfillment change; matches the order.fulfillment.updated webhook.

Formatint64
referenceId?|

Your own order reference, when one was sent.

customer?|

The traveller who paid on your hosted site, masked; null unless the origin is site, and once the traveller's details are deleted at the end of their retention period.

Example Request
curl -X POST 'https://api.sandbox.openroam.com/v1/flights/order' \  -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \  -H 'Content-Type: application/json' \  -d '{  "currency": "USD",  "referenceId": "partner-trip-7",  "items": [    {      "publicId": "flight_r2dm7x4q9v3b6n8c1z5k0t2w4y",      "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": "533380006",                "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": "533380007",                "issuingCountryCode": "GB",                "expiresOn": "2030-01-31"              }            ]          }        ],        "selectedServices": [          {            "id": "flight_s8d2k4m6n1p3q5r7t9v0w2x4y6",            "quantity": 1          }        ],        "maxPrice": {          "amount": 1250,          "currency": "USD"        }      }    }  ]}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "origin": {    "channel": "api"  },  "status": "paymentPending",  "total": {    "amount": 0,    "currency": "string"  },  "refunded": {    "amount": 0,    "currency": "string"  },  "payment": {    "status": "pending",    "method": "balance",    "amount": {      "amount": 0,      "currency": "string"    },    "wallet": {      "label": "string",      "debited": {        "amount": 0,        "currency": "string"      }    },    "failure": {      "code": 0,      "name": "string",      "message": "string"    }  },  "items": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5",      "productType": "flight",      "price": {        "amount": 0,        "currency": "string"      },      "purchasedProduct": {        "name": "string",        "countryCode": "string",        "logoUrl": "string",        "inputs": {          "passengers": [            {              "passengerIndex": 0,              "title": "string",              "givenName": "string",              "familyName": "string",              "gender": "string",              "bornOn": "2019-08-24",              "email": "string",              "phoneNumber": "string",              "identityDocuments": [                {                  "type": "passport",                  "uniqueIdentifier": "string",                  "issuingCountryCode": "string",                  "expiresOn": "2019-08-24"                }              ],              "selectedSeats": [                {                  "sliceIndex": 0,                  "segmentIndex": 0,                  "seatDesignator": "string"                }              ]            }          ],          "selectedServices": [            {              "id": "string",              "type": "other",              "passengerIndex": 0,              "sliceIndex": 0,              "segmentIndex": 0,              "quantity": 0            }          ]        },        "details": {          "owner": {            "iataCode": "string",            "name": "string",            "logoUrl": "string"          },          "slices": [            {              "origin": {                "iataCode": "string",                "icaoCode": "string",                "name": "string",                "city": "string",                "cityIataCode": "string",                "countryCode": "string",                "terminal": "string",                "timezone": "string"              },              "destination": {                "iataCode": "string",                "icaoCode": "string",                "name": "string",                "city": "string",                "cityIataCode": "string",                "countryCode": "string",                "terminal": "string",                "timezone": "string"              },              "departureAt": "2019-08-24T14:15:22Z",              "departureLocalTime": "2026-12-01T08:30:00",              "arrivalAt": "2019-08-24T14:15:22Z",              "arrivalLocalTime": "2026-12-01T08:30:00",              "durationMinutes": 0,              "stops": 0,              "segments": [                {                  "origin": {                    "iataCode": "string",                    "icaoCode": "string",                    "name": "string",                    "city": "string",                    "cityIataCode": "string",                    "countryCode": "string",                    "terminal": "string",                    "timezone": "string"                  },                  "destination": {                    "iataCode": "string",                    "icaoCode": "string",                    "name": "string",                    "city": "string",                    "cityIataCode": "string",                    "countryCode": "string",                    "terminal": "string",                    "timezone": "string"                  },                  "departureAt": "2019-08-24T14:15:22Z",                  "departureLocalTime": "2026-12-01T08:30:00",                  "arrivalAt": "2019-08-24T14:15:22Z",                  "arrivalLocalTime": "2026-12-01T08:30:00",                  "durationMinutes": 0,                  "marketingCarrier": {                    "iataCode": "string",                    "name": "string",                    "logoUrl": "string"                  },                  "marketingFlightNumber": "string",                  "operatingCarrier": {                    "iataCode": "string",                    "name": "string",                    "logoUrl": "string"                  },                  "operatingFlightNumber": "string",                  "aircraft": {                    "iataCode": "string",                    "name": "string",                    "imageUrl": "string"                  },                  "cabinClass": "economy",                  "stops": [                    {                      "airport": {                        "iataCode": "string",                        "icaoCode": "string",                        "name": "string",                        "city": "string",                        "cityIataCode": "string",                        "countryCode": "string",                        "terminal": "string",                        "timezone": "string"                      },                      "arrivingAt": "2019-08-24T14:15:22Z",                      "arrivingLocalTime": "2026-12-01T08:30:00",                      "departingAt": "2019-08-24T14:15:22Z",                      "departingLocalTime": "2026-12-01T08:30:00",                      "durationMinutes": 0                    }                  ],                  "baggage": [                    {                      "type": "unknown",                      "quantity": 0,                      "weightKg": 0,                      "description": "string"                    }                  ],                  "isCodeshare": true                }              ]            }          ],          "cabinClass": "economy",          "terms": {            "payment": {              "type": "payNow",              "dueNow": {                "amount": 0,                "currency": "string"              },              "dueLater": {                "amount": 0,                "currency": "string"              },              "dueLaterAt": "property"            },            "cancellation": {              "type": "fullyRefundable",              "freeUntil": "2019-08-24T14:15:22Z",              "freeUntilLocalTime": "2026-12-01T08:30:00",              "timezone": "string",              "schedule": [                {                  "from": "2019-08-24T14:15:22Z",                  "fromLocalTime": "2026-12-01T08:30:00",                  "refund": {                    "amount": 0,                    "currency": "string"                  },                  "penalty": {                    "amount": 0,                    "currency": "string"                  }                }              ],              "fee": {                "amount": 0,                "currency": "string"              }            },            "changes": {              "allowed": true,              "fee": {                "type": "fixed",                "amount": {                  "amount": 0,                  "currency": "string"                },                "percent": 0,                "min": {                  "amount": 0,                  "currency": "string"                },                "max": {                  "amount": 0,                  "currency": "string"                }              }            }          },          "includedBaggage": [            {              "type": "unknown",              "quantity": 0,              "weightKg": 0,              "description": "string"            }          ],          "selectedServices": [            {              "type": "other",              "label": "string",              "passengerIndex": 0,              "sliceIndex": 0,              "segmentIndex": 0,              "quantity": 0            }          ],          "priceLines": [            {              "description": "string",              "amount": {                "amount": 0,                "currency": "string"              },              "quantity": 0,              "serviceType": "other",              "category": "fare"            }          ],          "totalDurationMinutes": 0,          "totalStops": 0        }      },      "fulfillment": {        "status": "pending",        "result": {          "details": {            "bookingStatus": "confirmed",            "ticketDocuments": [              {                "type": "electronicTicket",                "uniqueIdentifier": "string"              }            ],            "booking": {              "slices": [                {                  "origin": {                    "iataCode": "string",                    "icaoCode": "string",                    "name": "string",                    "city": "string",                    "cityIataCode": "string",                    "countryCode": "string",                    "terminal": "string",                    "timezone": "string"                  },                  "destination": {                    "iataCode": "string",                    "icaoCode": "string",                    "name": "string",                    "city": "string",                    "cityIataCode": "string",                    "countryCode": "string",                    "terminal": "string",                    "timezone": "string"                  },                  "departureAt": "2019-08-24T14:15:22Z",                  "departureLocalTime": "2026-12-01T08:30:00",                  "arrivalAt": "2019-08-24T14:15:22Z",                  "arrivalLocalTime": "2026-12-01T08:30:00",                  "durationMinutes": 0,                  "stops": 0,                  "segments": [                    {                      "origin": {                        "iataCode": "string",                        "icaoCode": "string",                        "name": "string",                        "city": "string",                        "cityIataCode": "string",                        "countryCode": "string",                        "terminal": "string",                        "timezone": "string"                      },                      "destination": {                        "iataCode": "string",                        "icaoCode": "string",                        "name": "string",                        "city": "string",                        "cityIataCode": "string",                        "countryCode": "string",                        "terminal": "string",                        "timezone": "string"                      },                      "departureAt": "2019-08-24T14:15:22Z",                      "departureLocalTime": "2026-12-01T08:30:00",                      "arrivalAt": "2019-08-24T14:15:22Z",                      "arrivalLocalTime": "2026-12-01T08:30:00",                      "durationMinutes": 0,                      "marketingCarrier": {                        "iataCode": "string",                        "name": "string",                        "logoUrl": "string"                      },                      "marketingFlightNumber": "string",                      "operatingCarrier": {                        "iataCode": "string",                        "name": "string",                        "logoUrl": "string"                      },                      "operatingFlightNumber": "string",                      "aircraft": {                        "iataCode": "string",                        "name": "string",                        "imageUrl": "string"                      },                      "cabinClass": "economy",                      "stops": [                        {                          "airport": {                            "iataCode": "string",                            "icaoCode": "string",                            "name": "string",                            "city": "string",                            "cityIataCode": "string",                            "countryCode": "string",                            "terminal": "string",                            "timezone": "string"                          },                          "arrivingAt": "2019-08-24T14:15:22Z",                          "arrivingLocalTime": "2026-12-01T08:30:00",                          "departingAt": "2019-08-24T14:15:22Z",                          "departingLocalTime": "2026-12-01T08:30:00",                          "durationMinutes": 0                        }                      ],                      "baggage": [                        {                          "type": "unknown",                          "quantity": 0,                          "weightKg": 0,                          "description": "string"                        }                      ],                      "isCodeshare": true                    }                  ]                }              ],              "cabinClass": "economy",              "passengers": [                {                  "passengerIndex": 0,                  "title": "string",                  "givenName": "string",                  "familyName": "string",                  "gender": "string",                  "bornOn": "2019-08-24",                  "email": "string",                  "phoneNumber": "string",                  "identityDocuments": [                    {                      "type": "passport",                      "uniqueIdentifier": "string",                      "issuingCountryCode": "string",                      "expiresOn": "2019-08-24"                    }                  ],                  "selectedSeats": [                    {                      "sliceIndex": 0,                      "segmentIndex": 0,                      "seatDesignator": "string"                    }                  ]                }              ],              "terms": {                "payment": {                  "type": "payNow",                  "dueNow": {                    "amount": 0,                    "currency": "string"                  },                  "dueLater": {                    "amount": 0,                    "currency": "string"                  },                  "dueLaterAt": "property"                },                "cancellation": {                  "type": "fullyRefundable",                  "freeUntil": "2019-08-24T14:15:22Z",                  "freeUntilLocalTime": "2026-12-01T08:30:00",                  "timezone": "string",                  "schedule": [                    {                      "from": "2019-08-24T14:15:22Z",                      "fromLocalTime": "2026-12-01T08:30:00",                      "refund": {                        "amount": 0,                        "currency": "string"                      },                      "penalty": {                        "amount": 0,                        "currency": "string"                      }                    }                  ],                  "fee": {                    "amount": 0,                    "currency": "string"                  }                },                "changes": {                  "allowed": true,                  "fee": {                    "type": "fixed",                    "amount": {                      "amount": 0,                      "currency": "string"                    },                    "percent": 0,                    "min": {                      "amount": 0,                      "currency": "string"                    },                    "max": {                      "amount": 0,                      "currency": "string"                    }                  }                }              },              "includedBaggage": [                {                  "type": "unknown",                  "quantity": 0,                  "weightKg": 0,                  "description": "string"                }              ],              "selectedServices": [                {                  "type": "other",                  "label": "string",                  "passengerIndex": 0,                  "sliceIndex": 0,                  "segmentIndex": 0,                  "quantity": 0                }              ],              "totalDurationMinutes": 0,              "totalStops": 0            }          }        },        "failure": {          "code": 0,          "name": "string",          "message": "string"        },        "progress": {          "code": "string",          "message": "string"        }      },      "actions": {        "amendment": {          "availability": "available",          "reason": "string"        },        "cancellation": {          "availability": "available",          "reason": "string"        },        "update": {          "availability": "available",          "reason": "string"        }      },      "createdAt": "2019-08-24T14:15:22Z",      "effectivePaidAmount": {        "amount": 0,        "currency": "string"      },      "refund": {        "status": "pending",        "amount": {          "amount": 0,          "currency": "string"        },        "updatedAt": "2019-08-24T14:15:22Z",        "wallet": {          "label": "string",          "credited": {            "amount": 0,            "currency": "string"          }        }      }    }  ],  "timeline": [    {      "status": "paymentPending",      "occurredAt": "2019-08-24T14:15:22Z"    }  ],  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "fulfillmentVersion": 0,  "referenceId": "string",  "customer": {    "email": "string",    "name": "string",    "phone": "string",    "language": "string",    "countryCode": "string"  }}