Create or update inventory restrictions
Use the OTA_HotelAvailNotif
endpoint to update the following elements in the Booking.com system:
- The number of rooms available per room type and date combination.
- Restrictions per room type, rate and date combination.
- close a room type on a specified date. Even if roomrates are open, the room type is not available for booking.
- Set past date updates up to 1 day in the past (follows Central European Time (CET) timezone). Updates more than 1 day in the past, return a
NOT_A_VALID_DATE
error. - You can also view whether a room type is closed. For more information, see RestrictionStatus.
Closing room type vs. room and rate combination
You can close availability at the:
- room type level: Useful when removing availability for all rooms of a room type that has multiple rate combinations.
- room type and rate combination level: Useful when removing availability for a room type satisfying a specific rate combination.
Consider the following inventory:
Room type | Rate | Price | Date period | Rooms to sell |
---|---|---|---|---|
Villa | Summer rate | 110 | Jul 15 - Aug 31 | 10 |
Villa | Peak season rate | 120 | Aug 05 - Aug 20 | 10 |
Villa | Off season rate | 90 | Nov 01 - Dec 10 | 10 |
Closing room type and rate combination
To close the availability of the Villa so that guests don't see availability from Nov 01 - Dec 10, you must close the room type (Villa) and rate combination (Off season rate) by providing the following parameters: room
, date
, rate
, closed
Closing a room type
To close the availability of a specific room type, say Villa, so that guests don't see availability for a specific period, you must close the room type (Villa) by providing the following parameters: room
, date
, closed
.
Before creating availability for a room that is closed, you must use the OTA_HotelAvailNotif
endpoint to open the room. Otherwise, the request to create availability completes successfully. But guests will not be able to see the availability as the room is still closed.
Header parameter
Header | Description | Type | Required/ Optional | Notes |
---|---|---|---|---|
Accept-Version | Specify the version number to get the API functionality specific to that version. | string | optional | Supports the following values: - 1.1: Current version. - 1.0: Sunset version. Do not use. |
Sample header
POST 'https://supply-xml.booking.com/hotels/ota/OTA_HotelAvailNotif' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblhWTdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'
Request (RQ) sent inventory and/or restrictions
POST https://supply-xml.booking.com/hotels/ota/OTA_HotelAvailNotif
Request — HTTP Message Body Model
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelAvailNotifRQ.xsd" TimeStamp="2023-10-05T14:20:50" Target="Test" Version="1.005">
<AvailStatusMessages>
<AvailStatusMessage BookingLimit="25" LocatorID="1">
<StatusApplicationControl Start="2023-11-05" End="2023-11-17" InvTypeCode="36745603" />
</AvailStatusMessage>
<AvailStatusMessage LocatorID="2">
<StatusApplicationControl Start="2023-11-05" End="2023-11-17" InvTypeCode="36745603" RatePlanCode="1278606" />
<LengthsOfStay>
<LengthOfStay Time="2" MinMaxMessageType="SetMinLOS" />
<LengthOfStay Time="5" MinMaxMessageType="SetMaxLOS" />
</LengthsOfStay>
<RestrictionStatus Status="Open" />
</AvailStatusMessage>
</AvailStatusMessages>
</OTA_HotelAvailNotifRQ>
The above example will do the following:
- Sets the rooms to sell for room 36745603 to 25 from the 5th of November to and including the 17th of November 2023.
- Sets the minimum stay through for room 36745603 and rate 1278606 to 2 nights from the 5th of November to and including the 17th of November 2023.
- Set Maximum Stay Through for room 36745603 and rate 1278606 to 5 nights from the 5th of November to and including the 17th of November 2023.
Element | Attribute | Description | Type | Required | Notes |
---|---|---|---|---|---|
OTA_HotelAvailNotifRQ | Root element | object | Yes | ||
TimeStamp | Specifies the current time and date. | datetime | Yes | Format: yyyy-MM-ddTHH:mm:ss | |
Target | Specifies environment. | string | Yes | Possible values: Production or Test | |
AvailStatusMessages | Root element for availability updates. | object | Yes | ||
AvailStatusMessage | Container for status messages. | object | Yes | ||
BookingLimit | Number of rooms to sell. | integer | No | Max value: 254. Values ≥255 default to 254. | |
LocatorID | Unique identifier. | string | Yes | Used as RecordID in response. | |
StatusApplicationControl | Root element for status application control. | object | Yes | ||
Start | Start date of period. You can update for periods in the future and up to one day in the past. | date | Yes | Format: yyyy-MM-dd | |
End | End date of period. Inclusive. | date | Yes | Format: yyyy-MM-dd | |
InvTypeCode | Booking.com room ID | string | Yes | - | |
RatePlanCode | Booking.com rate plan ID. | string | No | Required when updating restrictions. Not required when specifying Bookinglimit in AvailStatusMessage , as the availability is updated on room level. | |
LengthsOfStay | Root element for length of stay. | object | No | ||
ArrivalDateBased | Restriction applies to arrival day. | boolean | No | Default: 0. Can be set to 0 or 1. If set to 1 , then the restriction set has an effect only on the arrival day of a booking. Whereas, setting it to 0 may affect a search for availability or reservation on all the dates that the query covers. The ArrivalDateBased attribute is optional and the default value is 0 . To set both length-of-stay restriction (ArrivalDateBased="0" ) and length-of-stay restriction on the arrival day (ArrivalDateBased="1" ), you must send those restrictions in separate AvailStatusMessage blocks. | |
LengthOfStay | Time | Number of days for min/max stay | integer | No | The minimum or maximum stay for the given room for the given date for the given rate plan. If a booking takes place on this day, a minimum or maximum stay (for the whole booking or arrival based, depending on ArrivalDateBased="0" or ArrivalDateBased="1" ) of this amount of days is required. Each day in a stay has a room and rate category ID associated with it. Each set of consecutive days with the same rate category ID in a stay, must comply with the minimum or maximum stay setting. |
MinMaxMessageType | Types of length of stay | string | No | Possible values: SetMinLOS or SetMaxLOS | |
RestrictionStatus | Root element for restriction status | object | No | ||
Status | Room availability status | string | No | Values: Open or Close . Close the specified room type. The room type will not be available for booking for the specified period, irrespective of whether the room has an open room and rate combination. To close the room type you must not include the RatePlanCode in the request. You can also close the availability for the specified room type and rate combination by specifying the RatePlanCode in the request. If set to Close (or Open ), the room is closed (or opened) for the specified date. When a room is closed, all other information such as Bookinglimit , prices, and so on is preserved. | |
Restriction | Type of restriction | string | No | Possible values: Departure or Arrival | |
MinAdvancedBookingOffset | Minimum advance booking time | string | No | Format: "nD" or "nH" or "nDnH". Max: 360D The search date is counted as one of the dates in the restriction. For example: * MinAdvancedBookingOffset="4D" means the room must be booked at least 4 days in advance. |
MinAdvancedBookingOffset="4H"
means the room must be booked at least 4 hours in advance.MinAdvancedBookingOffset="4D4H"
means the room must be booked at least 4 days and 4 hours in advance.
To set restrictions usingMinAdvanceBookingOffset
orMaxAdvanceBookingOffset
you must pass aRatePlanCode
. If aRatePlanCode
is not passed, the API returns an error.
Response
OTA_HotelAvailNotifRS
All the below code is fixed, except:
TimeStamp
: Contains the current time.
Target
: Set to same value as in the corresponding OTA_HotelAvailNotifRQ
.
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelAvailNotifRS.xsd" TimeStamp="2023-10-11T15:30:04-00:00" Target="Test" Version="1.004">
<Success />
</OTA_HotelAvailNotifRS>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXX] -->
Troubleshooting
HTTP error code behaviour on v1.1
The following table captures all the common conditions and the HTTP error codes that the v1.1 endpoint returns.
If the endpoint encounters | The endpoint returns |
---|---|
Incorrect username or password. | HTTP 401 |
Schema validations such as invalid integer, date. | HTTP 400 |
All updates with errors. | HTTP 400 |
At least one successful update. | HTTP 200 in addition to errors or warnings, if any. |
All updates are unauthorized. | HTTP 403 |
Error codes on v1.1
The following table summarises the error codes for the OTA_HotelAvailNotif
endpoint.
Error code | Error message | Notes |
---|---|---|
AUTHENTICATION_FAILURE | Authentication failed for the request | The credentials provided in the request was not sufficient for a successful authentication check. To fix a failed authentication request, see the Authentication page. |
CURRENCY_SWITCH_IN_PROGRESS | There is a hotel currency switch currently in progress | You need to wait until hotel switch currency. |
DATE_ELEMENT_MISSING | Date is missing | Date is required for this request. |
EXCEEDS_MAX_RELATIVE_RELEASE_TIME | Relative release time {release_time} exceeds max allowed value. This is not the case for room id{room_id}, rate id {rate_id} on date{date} | You are setting release time that exceeds the maximum allowed value. |
FROM_DATE_SHOULD_BE_LESS_THAN_TO_DATE | From date should be less than or equal To Date | The From date should be less than or equal to the To date. |
HOTEL_ACCESS_DENIED | Request for forbidden hotel id(s) | Check the property ID and either provide the correct property ID or make sure the machine account credentials have enough permissions. |
HOTEL_HAS_MISCONFIGURED_UFI | The timezone value is missing for the Ufi associated with hotel ID $hotel_id | Check the property's UFI configuration. |
INTERNAL_SERVER_ERROR | Internal server error | Booking.com service failed. |
NOT_A_VALID_DATE | INVALID_DATE | The supplied date format is invalid. The valid format is yyyy-mm-dd . Or, the supplied date is more than 1 day in the past. |
NOT_A_VALID_RELEASE_TIME | Release times should be in the expected format. This is not the case for room ID $room_id, rate ID $rate_id on date '$date' | Make sure to specify the release time in the expected format. |
RATE_EDITABLE_ONLY_ON_EXTRANET | Rate '%s' is only editable on Extranet | You are not allowed to edit the rate via the connectivity API. The property can edit the rate via the Booking.com extranet. |
RATE_ID_REQUIRED | Rate Id is required | Rate id is required for this request. |
RATE_IS_A_SLAVE_RATE | You cannot set $attribute for a child rate $rate_id, since they are automatically set based on Rate Relations | Cannot update a child rate. |
RATE_NOT_ACTIVE_FOR_ROOM | Rate '%s' is not active for room '%s' | Rate is not activated for the selected room. Please check allowed roomrates using the roomrates endpoint. |
ROOM_EDITABLE_ONLY_ON_EXTRANET | Room '%s' is only editable on Extranet | You are not allowed to edit the room via the connectivity API. The property can edit the room via Booking.com extranet. |
ROOM_ELEMENT_REQUIRED | Room is missing | The request contains an empty request body. |
ROOM_ID_INVALID | Room ID '%s' is not valid | Provide a valid Room ID. Make sure to retrieve the correct Room ID using the [rooms endpoint][retrieving-room-types]. |
ROOM_ID_MISSING | Room ID is missing | Room ID is required for the request. |
TYPE_VIOLATION | Generic error when provided data type is different than specified. |
Success response example
Success element is optional, depending on whether the request contained errors.
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelAvailNotifRS.xsd" TimeStamp="2023-10-05T12:20:50-00:00" Target="Test" Version="1.004">
<Success />
</OTA_HotelAvailNotifRS>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXX] -->
Warning response example
Warnings can be combined with success messages if the request was still processed.
Type: OTA error code (see OTA codetable).
Code: OTA EWT code (see OTA codetable).
RecordID: same as LocatorID in OTA_HotelAvailNotifRQ.
Status: NotProcessed (error) / Complete (only warning).
ShortText (may be empty): warning message.
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelAvailNotifRS.xsd" TimeStamp="2023-10-11T15:32:03-00:00" Target="Test" Version="1.004">
<Success />
<Warnings>
<Warning Type="1" Code="367" Status="Complete" ShortText="Rooms to Sell were set below the Minimum Contracted rooms for these dates: 2023-11-15, 2023-11-07, 2023-11-12, 2023-11-13, 2023-11-08, 2023-11-09, 2023-11-17, 2023-11-14, 2023-11-06, 2023-11-11, 2023-11-16, 2023-11-05, 2023-11-10. The values have been amended to the Minimum Contracted Rooms."/>
</Warnings>
</OTA_HotelAvailNotifRS>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX] -->
Errors
Errors are optional and only used alone, without success/warnings.
Code: OTA EWT code (see OTA codetable).
Type: OTA error code (see OTA codetable).
RecordID: same as LocatorID in OTA_HotelAvailNotifRQ.
Status: NotProcessed.
ShortText (may be empty): error message.
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelAvailNotifRS.xsd" TimeStamp="2023-10-12T07:36:16-00:00" Target="Test" Version="1.004">
<Errors>
<Error Type="1" Code="367" Status="NotProcessed" ShortText="xml parse error"/>
</Errors>
</OTA_HotelAvailNotifRS>
The Booking.com responses will contain a RUID
string, which is an encoded string used by the Booking.com staff to trace back any updates made before. Whenever the Connectivity Partner wishes the XML-Team to look at any logfiles for debugging or the like; the RUID
string needs to be provided. This will enable the Booking.com technical staff to provide Connectivity Partners with support.
RUID
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX] -->