Hotel orders

An order is a booking made from a confirmed rate. You create it to hold the room, then place the order. You can read it, preview and run a cancellation, and extend the payment deadline.

Lifecycle

status	Meaning
`held`	The room is held until the payment deadline. Cancellable.
`confirming`	The order has been placed and is being finalized.
`confirmed`	The booking is confirmed; a voucher and confirmation number are issued.
`cancelled`	The order was cancelled; the hold is released.

Create an order

POST/v3/HAPI/hotels/orders

Requires the hotels:write scope. Confirm the rate first (confirm a rate) in the same session, or this returns 409 rate_not_revalidated.

Body

Field	Type	Required	Description
`rate_id`	string	Yes	The confirmed `hrt_` id.
`rooms`	array	Yes	One entry per room, each with its guests.
`rooms[].guests[].given_name`	string	Yes	Guest first name.
`rooms[].guests[].family_name`	string	Yes	Guest last name.
`rooms[].guests[].type`	string	No	`adult` (default) or `child`.
`rooms[].guests[].title`	string	No	`mr`, `mrs`, `ms`, `miss`.
`contact.email`	string	Yes	Contact email.
`contact.phone`	string	Yes	Contact phone.
`nationality`	string	No	Lead guest nationality.
`note`	string	No	A note for the hotel.
`client_reference`	string	No	Your own reference.

curl -X POST https://api.hermeseus.com/v3/HAPI/hotels/orders \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f2b8c1a-3e4d-4a6b-9c7e-1d2f3a4b5c6d" \
  -d '{
    "rate_id": "hrt_Ym9va2FwcDphYmMxMjM",
    "rooms": [
      { "guests": [
        { "given_name": "Jane", "family_name": "Doe", "type": "adult", "title": "ms" }
      ] }
    ],
    "contact": { "email": "jane@example.com", "phone": "+14155550100" },
    "nationality": "US"
  }'

Response

{
  "object": "hotel_order",
  "id": "hord_8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
  "status": "held",
  "payment_deadline": "2026-11-13T20:00:00+00:00",
  "check_in": "2026-11-14",
  "check_out": "2026-11-16",
  "nights": 2,
  "total": { "amount": "360.00", "currency": "USD" },
  "confirmation_number": null,
  "voucher_number": null,
  "hotel_pnr": null,
  "hotel": { /* … */ },
  "contact": { "phone": "+14155550100", "email": "jane@example.com" },
  "rooms": [ /* booked rooms */ ],
  "cancellation": { "non_refundable": false, "policy_text": "…", "policies": [ /* … */ ] }
}

Status	Code	Meaning
402	`insufficient_balance`	The office wallet cannot cover the rate.
409	`duplicate_booking`	An active order already exists for this rate.
409	`rate_not_revalidated`	Confirm the rate before ordering.

Read an order

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

Requires hotels:read. Returns the hotel_order, with the confirmation and voucher numbers once confirmed.

Confirm the order

POST/v3/HAPI/hotels/orders/{id}/confirm

Requires hotels:write. Places a held order. Poll the order until it becomes confirmed.

Cancel an order

Preview the penalty, then cancel.

GET/v3/HAPI/hotels/orders/{id}/cancellation

{
  "object": "hotel_cancellation_quote",
  "order_id": "hord_8f3c81d2-…",
  "penalty": { "amount": "0.00", "currency": "USD" },
  "status": 2,
  "expires_at": "2026-11-13T21:00:00+00:00"
}

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

Requires hotels:write. Cancels the order and releases the hold; the order becomes cancelled.

Extend the payment deadline

POST/v3/HAPI/hotels/orders/{id}/extend-deadline

Requires hotels:write. Pushes the payment deadline out on a held order.

{ "object": "hotel_order", "id": "hord_8f3c81d2-…", "payment_deadline": "2026-11-13T20:30:00+00:00" }

Was this page helpful?

Confirm a rate

Browse products