Best practices for Reservation API implementation¶
How to react to HTTP 500 errors¶
Sometimes a Booking.com API will return an HTTP status code 500, 502, or other 5XX. For the Reservation API, it is important to follow web protocol best practices, to ensure that all reservations are delivered even when there is a temporary system fault.
OTA API calls that confirm messages (OTA_HotelResNotifRS/OTA_HotelResModifyNotifRS) must be retried until a result other than HTTP 5XX is obtained. When Booking.com sends a result of 5XX for these requests, it means that the message is still pending delivery. If the message remains pending delivery for 30 min, then online delivery may be aborted and the message falls back to email delivery instead.
Processes that fetch new reservation data (B.XML
reservations and OTA_HotelResNotifRQ/
HotelResModifyNotifRQ) should normally cover any available reservation within a few minutes.
Therefore, the best error-handling strategy for HTTP 5XX is to do nothing special for it,
because the next normal poll will serve as the retry. It is important to avoid retrying
with zero delay, because such a retry is unlikely to succeed and it may unduly increase
the server loads at Booking.com.
Do send acknowledge message to confirm message delivery¶
Always remember to send an acknowledge message after retrieving reservations.
An OTA acknowledge message confirms positively that the new information is visible within the online system used by the partner. If Booking.com does not receive the acknowledgement, then it is assumed that the partner is not receiving any update.
Use the OTA error facility and do not allow messages to time out¶
If a reservation fetched is inaccurate or unable to be processed, a rejection should be sent back rather than silently ignoring it, which will lead to fallback after it times out.
For more information, see "OTA_HotelResNotif Response".
Register planned maintenance downtime on the Portal¶
If reservations are not picked up and acknowledged after 30 minutes, fallbacks will be sent to properties. Hold is a feature which will prevent fallbacks being sent for the time period when it's turned on. Please plan maintenance at least 24 hours in advance and enter the schedule on the Provider Portal.
reservationssummary to import reservations for a newly onboarded property¶
Of all Reservation API facilities, only
provides all currently booked reservations, including older ones which were confirmed
before the property became connected.
The other API calls are limited to reservations created or modified in the last two weeks and booked after the property became connected.
Do not periodically query each single
Querying all reservations using one
hotel_id at a time is likely to create service
interruptions for individual partners. We have found this practice to be associated
with email fallbacks.
Do not use multiple
hotel_ids per query (unless they are the same partner)¶
Similar to querying using a single
hotel_id, using multiple
hotel_ids will increase the chance of failing to pick up
reservations in time. Furthermore, if any of the hotel_ids are not accessible to the machine account which is sending
the request, there will be errors and it will affect points in the Preferred Programme.
It's acceptable to use this query style if the
hotel_ids share a common operator or front desk.
Do not use
last_changed (except in special cases¶
last_changed query parameter causes the response to include confirmations, modifications and cancellations regardless of
what endpoint is being called. Besides that, because the response already can contain already processed data, it also increases the likelihood that the reservations API:
- Does not process new reservations.
- Does not send acknowledgements in time.
Our API selects only messages that have not yet been delivered by default, so the
last_changed query parameter is
An example of reasonable use of
last_changed would be a server failure causing the loss
of reservation data including the booking numbers (reservation IDs). But if the IDs are
known, it is more reliable to provide them to the API instead of last_changed.
Typically, you should download and store reservation data, and then present it to the user. It is not necessary to refresh reservations with extra queries. Please report any doubts or concerns to firstname.lastname@example.org.
Always include a Hotel ID when querying a reservation ID¶
It is recommended that you provide a hotel ID with every reservation ID query. In the future this will become a requirement.
Prefer OTA protocol over B.XML¶
If possible, implement the OTA protocol as it offers more safeguards and more features.
Use OTA API hotel reservation response tokens and properly handle HTTP 409¶
The Reservation API offers the "OTA hotel reservation response token" or
feature to improve reliability. It is found on the Feature Management page
including an on/off switch and extensive documentation.
These tokens identify each confirmation message with specific reservation data from
OTA_HotelResModifyNotifRQ. If the data becomes outdated
before it is confirmed, then the API responds to the confirmation with the HTTP status,
409 CONFLICT, and an error message,
for hotel reservation does not match. Please pull again (error code 756)
At this point, confirmation is impossible, so the confirmation should not be retried.
Instead, the reservation should be updated using a new
A new confirmation should then be applied on the new data.
OTA_HotelResModifyNotifRQ is retrieved frequently for all properties,
the no special action is needed: Simply treat the HTTP 409 response the same as an HTTP 200.
The next pull will retrieve another update. This simple implementation strategy does still
benefit from the reliability added by the feature.
Use machine accounts to segment the user base¶
Using well-organized machine accounts not only prevents too many reservations sending to a single account, but also keeps partner accounts categorised and makes it easier for support to pin down errors if they occur.