Skip to content

BookingHold

POST {base_url}/1.0/bookings/hold

Blocks a specific room and rate for 5 minutes to give time to confirm.

Header Value
Authorization Bearer <access_token>
Content-Type application/json
Accept application/json
{
"rateKey": "<rateKey from /hotels/checkrates>"
}
Field Type Description
rateKey string See the rateKey source warning above
client object Optional. Booking holder
client.name string First name
client.surname string Last name
client.contactData[].email string Email
client.contactData[].phone.countryCode string Country code
client.contactData[].phone.number string Phone number
roomCriteria[] array Optional. One entry per room
roomCriteria[].roomId int Room number within the quote, from 1 to N, in the order the rooms were requested in HotelRates — see Guest data in the hold
roomCriteria[].paxes[] array Guests in the room
roomCriteria[].paxes[].age int Guest age
roomCriteria[].paxes[].name string Guest name
roomCriteria[].paxes[].surname string Guest surname

BookingHold optionally accepts client and roomCriteria, sent together as in the example below. This flow coexists with the current one: client can still be sent in BookingNew, as documented in BookingNew.

  • Send roomId from 1 to N in the order of the rooms in HotelRates, and send the roomCriteria array in that same order.
  • For each room, send the same guests (count and ages) that were quoted in HotelRates.

Example request with two rooms, one of them with a minor:

{
"rateKey": "<rateKey from /hotels/checkrates>",
"client": {
"name": "Jane",
"surname": "Doe",
"contactData": [
{
"email": "jane.doe@example.com",
"phone": {
"countryCode": "+52",
"number": "5512312322"
}
}
]
},
"roomCriteria": [
{
"roomId": 1,
"paxes": [
{ "age": 30, "name": "Jane", "surname": "Doe" },
{ "age": 32, "name": "John", "surname": "Doe" }
]
},
{
"roomId": 2,
"paxes": [
{ "age": 41, "name": "Maria", "surname": "Lopez" },
{ "age": 10, "name": "Ana", "surname": "Lopez" }
]
}
]
}

BookingNew request in this flow:

{
"bookingKey": "<bookingKey from /bookings/hold>",
"clientReference": "99999",
"commentsForHotel": "Special requests..."
}

Observed in one sample:

  • BookingNew was accepted with only bookingKey, clientReference and commentsForHotel.
  • In BookingGet, the primaryGuest of each room was the first guest of that room.
{
"bookingKey": "oDvxthDyTDD9xNd...XYZ=",
"eventId": "441542bd-f08e-40ed-81e9-11fbd08b0915",
"error": null
}
Field Type Description
bookingKey string Token used in BookingNew. Valid 5 minutes.
eventId string Trace ID
error object|null Error details, or null on success

The bookingKey expires 5 minutes after issue. After expiry, the room is released and you must restart from CheckRates (or earlier).

Code HTTP Message Cause What to do
1101 400 The provided key has already been used previously rateKey already used in a Hold Get a new rateKey with CheckRates
4001 400 Invalid Hold Request, can not parse the rateKey rateKey corrupted, encoded incorrectly, or empty Send the rateKey from CheckRates complete and unmodified
4002 400 You cannot invoke 'Hold' without first performing a 'CheckRates' Hold called with the rateKey from Rates instead of CheckRates Use the rateKey returned by CheckRates, not by Rates
4003 400 RateKey from CheckRates older than 20 min The rateKey from CheckRates is older than 20 min Repeat CheckRates
Symptom Likely cause
4001 with valid-looking rateKey The rateKey contains URL-unsafe characters (+, /, =) — verify it is being sent in JSON body, not as URL param
4002 Calling Hold with the rateKey from /rates instead of /checkrates
1101 on retry The previous Hold succeeded silently; check for a bookingKey in your logs

Some implementations send an additional header for tracking; it is not validated by the API but can be useful in logs:

Header Purpose
CustomerIp Originating customer IP for analytics

This header is optional. Its presence does not change behavior.