Booking Flow
Full flow
Section titled “Full 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
CONFIRMEDbooking may not yet have the hotel confirmation number; it becomes available later inhotels[].confirmationCodethrough BookingGet — see BookingNew. clientcan be sent in BookingNew (current flow) or, together with the guests per room (roomCriteria), in BookingHold — see Guest data in the hold.
Mandatory chaining rules
Section titled “Mandatory chaining rules”| 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 |
Multi-room queries
Section titled “Multi-room queries”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.
Modifications
Section titled “Modifications”The API does not support booking modifications. To “modify” a booking, you must:
- Cancel the existing booking (90s minimum after creation).
- Create a new booking with the desired changes.
Performance limits
Section titled “Performance limits”- Max 50 hotel IDs per
/hotels/ratescall. - Max 28 days stay range per query.
- Rate-limited per channel (HTTP 429 on excess).
Common flow mistakes
Section titled “Common flow mistakes”| 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+ |

