Flight orders

An order is a booking made from a revalidated offer. You create it to hold the seats, then request ticket issuance. Along the way you can read it, cancel it before it is ticketed, refund it after, and attach notes.

Lifecycle

An order moves through a small set of states:

status	Meaning
`held`	Seats are held; the ticket is not issued. Cancellable.
`ticketing`	Issuance has been requested and is in progress.
`ticketed`	The ticket is issued. Use refund, not cancel.
`cancelled`	The held order was voided; the hold is released.
`refunded`	An issued ticket was refunded.

Create an order

POST/v3/HAPI/flights/orders

Requires the flights:write scope. Revalidate the offer first (get the offer) in the same session, or this returns 409 offer_not_revalidated.

Body

Field	Type	Required	Description
`offer_id`	string	Yes	The revalidated `ofr_` id.
`passengers`	array	Yes	One entry per traveller.
`passengers[].type`	string	Yes	`adult`, `child`, or `infant`.
`passengers[].given_name`	string	Yes	First name.
`passengers[].family_name`	string	Yes	Last name.
`passengers[].date_of_birth`	string	Yes	`YYYY-MM-DD`.
`passengers[].gender`	string	Yes	`male` or `female`.
`passengers[].nationality`	string	No	Nationality code.
`passengers[].document`	object	No	Passport: `number`, `expires_on`, `country_code`, `issued_on`.
`contact.email`	string	Yes	Contact email.
`contact.phone`	string	Yes	Contact phone.
`client_reference`	string	No	Your own reference, echoed back and usable for idempotent lookups.

curl -X POST https://api.hermeseus.com/v3/HAPI/flights/orders \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f2b8c1a-3e4d-4a6b-9c7e-1d2f3a4b5c6d" \
  -d '{
    "offer_id": "ofr_dHJhdmVscGF5b3V0cz...",
    "passengers": [
      {
        "type": "adult",
        "given_name": "Jane",
        "family_name": "Doe",
        "date_of_birth": "1990-05-01",
        "gender": "female",
        "nationality": "US",
        "document": {
          "number": "X1234567",
          "expires_on": "2030-01-01",
          "country_code": "US",
          "issued_on": "2020-01-01"
        }
      }
    ],
    "contact": { "email": "jane@example.com", "phone": "+14155550100" }
  }'

Response

A flight_order in the held state, with the ticketing deadline.

{
  "object": "flight_order",
  "id": "ord_8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
  "status": "held",
  "ticketing_deadline": "2026-11-13T20:00:00+00:00",
  "validating_airline": "PC",
  "total": { "amount": "412.00", "currency": "USD" },
  "base":  { "amount": "250.00", "currency": "USD" },
  "tax":   { "amount": "162.00", "currency": "USD" },
  "contact": { "email": "jane@example.com", "phone": "+14155550100" },
  "passengers": [
    { "type": "adult", "given_name": "Jane", "family_name": "Doe",
      "date_of_birth": "1990-05-01", "gender": "female", "nationality": "US",
      "document": { "number": "X1234567", "expires_on": "2030-01-01",
                    "country_code": "US", "issued_on": "2020-01-01" },
      "ticket_number": null, "pnr": null }
  ],
  "segments": [
    { "origin": "IST", "destination": "DXB",
      "departing_at": "2026-11-14T08:10:00", "arriving_at": "2026-11-14T11:15:00",
      "marketing_carrier": "PC", "flight_number": "695",
      "cabin_class": "economy", "booking_class": "Y", "stops": 0, "pnr": null }
  ],
  "notes": [],
  "price_change": false
}

Status	Code	Meaning
402	`insufficient_balance`	The office wallet cannot cover the fare. Top up and retry.
409	`duplicate_booking`	An active order already exists for this offer.
409	`offer_not_revalidated`	Revalidate the offer before ordering.

Read an order

GET/v3/HAPI/flights/orders/{id}

Requires flights:read. Returns the same flight_order shape, with the current status, ticket numbers, and PNR once issued.

Issue the ticket

POST/v3/HAPI/flights/orders/{id}/ticket

Requires flights:write. Moves a held order to ticketing. Poll the order until it becomes ticketed, at which point ticket_number and pnr are populated on each passenger.

Cancel an order

POST/v3/HAPI/flights/orders/{id}/cancellation

Requires flights:write. Voids a held order and releases the hold. An order that is already ticketed returns 409 order_ticketed; use a refund instead.

Refund an order

First preview the terms, then request the refund.

GET/v3/HAPI/flights/orders/{id}/refund

Requires flights:read. Returns a refund_quote with the penalty per ticket.

{
  "object": "refund_quote",
  "order_id": "ord_8f3c81d2-…",
  "refund_type": 1,
  "tickets": [
    { "ticket_number": "235-1234567890", "status": 1, "is_refunded": false,
      "non_refundable": false, "penalty": { "amount": "40.00", "currency": "USD" },
      "route": "IST-DXB", "pnr": "ABC123" }
  ]
}

POST/v3/HAPI/flights/orders/{id}/refund

Requires flights:write. Optional body: refund_type, ticket_numbers, refund_payment_mode. On success the order becomes refunded.

{
  "object": "refund",
  "order_id": "ord_8f3c81d2-…",
  "status": "requested",
  "refunded_tickets": ["235-1234567890"]
}

Add notes

POST/v3/HAPI/flights/orders/{id}/notes

Requires flights:write. Attach free-text notes to the order.

curl -X POST https://api.hermeseus.com/v3/HAPI/flights/orders/ord_8f3c81d2-.../notes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "notes": ["Traveller requested a window seat."] }'

The updated flight_order is returned, with the notes appended.

Was this page helpful?

Fare conditions

Search destinations