Skip to content

Booking Flow

1. Token (auth, valid ~1h)
│
▼
2. HotelRates (search, returns rateKey valid 60 min)
│
▼
3. CheckRates (validate rate, returns NEW rateKey valid 20 min)
│
▼
4. BookingHold (block inventory, returns bookingKey valid 5 min)
│
▼
5. BookingNew (confirm reservation, returns bookingId)
│
├─→ BookingGet (retrieve booking details by ID)
└─→ BookingDelete (cancel — wait 90s after creation)
  • If BookingNew times out or returns a 5xx error, do not restart the flow — see the retry strategy in BookingNew.
  • A CONFIRMED booking may not yet have the hotel confirmation number; it becomes available later in hotels[].confirmationCode through BookingGet — see BookingNew.
  • client can be sent in BookingNew (current flow) or, together with the guests per room (roomCriteria), in BookingHold — see Guest data in the hold.
Step Input Output TTL
Token client_id + client_secret access_token ~1 hour
Rates hotelIds + dates + paxes rateKey (rates) 60 min
CheckRates rateKey from Rates rateKey (checkrates) 20 min
BookingHold rateKey from CheckRates bookingKey 5 min
BookingNew bookingKey bookingId n/a

The Rates service supports querying multiple rooms simultaneously. The response only returns room types where the same room is available for all requested rooms.

  • One rateKey per response represents the total cost of all rooms combined.
  • Do not select multiple rateKeys for a multi-room booking — one rateKey already includes all rooms.

Example: requesting 2 rooms returns only types where 2 of the same room are available; rateKey amount = cost of both rooms.

The API does not support booking modifications. To “modify” a booking, you must:

  1. Cancel the existing booking (90s minimum after creation).
  2. Create a new booking with the desired changes.
  • Max 50 hotel IDs per /hotels/rates call.
  • Max 28 days stay range per query.
  • Rate-limited per channel (HTTP 429 on excess).
Mistake Symptom Fix
Skipping CheckRates before Hold Error 4002 on /bookings/hold Always call CheckRates first
Using stale rateKey (>60 min) Error 4001 / 4006 / sold_out Re-search via /hotels/rates
Calling Cancel <90s after Booking Error 1203 (reservation still being created) Wait at least 90 seconds
Booking with rateKey from Rates instead of CheckRates Error 4002 on Hold Use the rateKey returned by CheckRates
Quoting >28 days Error 3003 Split into multiple queries
CheckIn in the past Error 3001 Use today or future dates
CheckOut <= CheckIn Error 3002 CheckOut must be strictly after CheckIn
Room without any adult Error 3004 Each room requires at least one pax aged 18+