Best practices for Reservation API implementation¶
How to handle HTTP 500 errors?¶
Sometimes a Booking.com API will return a response with 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 timeout¶
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 the timeout.
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.
More information: Reservation holds
To place a hold: Company Settings
Use reservationssummary to import reservations for a newly onboarded property¶
The reservationssummary endpoint
provides all currently booked reservations, including older reservations 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 hotel_id¶
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)¶
Booking.com does not recommend an excessive use of the last_changed parameter as it may lead to unexpected behaviour. Use this parameter only when you have to recover lost data after an unexpected outage.
When retrieving reservations using the last_changed query parameter, the API response includes confirmations, modifications and cancellations that may have already been processed. Processing that response can impact your system's availability to:
- Process new reservations.
- Send acknowledgements in time.
Without the last_changed query parameter, the Reservations API selects only messages that have not yet been delivered or processed succesfully.
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 connectivity@booking.com.
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 ota_res_response_token
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_HotelResNotifRQ or 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 the error message:
Response token <token_id> for hotel reservation <reservation_id> 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 OTA_HotelResModifyNotifRQ.
A new confirmation should then be applied on the new data.
Assuming that 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.