Last updated

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 typeRatePriceDate periodRooms to sell
VillaSummer rate110Jul 15 - Aug 3110
VillaPeak season rate120Aug 05 - Aug 2010
VillaOff season rate90Nov 01 - Dec 1010

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.

Once a room is closed you must open it before creating availability

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

HeaderDescriptionTypeRequired/
Optional
Notes
Accept-VersionSpecify the version number to get the API functionality specific to that version.stringoptionalSupports 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.
ElementAttributeDescriptionTypeRequiredNotes
OTA_HotelAvailNotifRQRoot elementobjectYes
TimeStampSpecifies the current time and date.datetimeYesFormat: yyyy-MM-ddTHH:mm:ss
TargetSpecifies environment.stringYesPossible values: Production or Test
AvailStatusMessagesRoot element for availability updates.objectYes
AvailStatusMessageContainer for status messages.objectYes
BookingLimitNumber of rooms to sell.integerNoMax value: 254. Values ≥255 default to 254.
LocatorIDUnique identifier.stringYesUsed as RecordID in response.
StatusApplicationControlRoot element for status application control.objectYes
StartStart date of period. You can update for periods in the future and up to one day in the past.dateYesFormat: yyyy-MM-dd
EndEnd date of period. Inclusive.dateYesFormat: yyyy-MM-dd
InvTypeCodeBooking.com room IDstringYes-
RatePlanCodeBooking.com rate plan ID.stringNoRequired when updating restrictions. Not required when specifying Bookinglimit in AvailStatusMessage, as the availability is updated on room level.
LengthsOfStayRoot element for length of stay.objectNo
ArrivalDateBasedRestriction applies to arrival day.booleanNoDefault: 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.
LengthOfStayTimeNumber of days for min/max stayintegerNoThe 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.
MinMaxMessageTypeTypes of length of staystringNoPossible values: SetMinLOS or SetMaxLOS
RestrictionStatusRoot element for restriction statusobjectNo
StatusRoom availability statusstringNoValues: 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.
RestrictionType of restrictionstringNoPossible values: Departure or Arrival
MinAdvancedBookingOffsetMinimum advance booking timestringNoFormat: "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 using MinAdvanceBookingOffset or MaxAdvanceBookingOffset you must pass a RatePlanCode. If a RatePlanCode 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 encountersThe 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 codeError messageNotes
AUTHENTICATION_FAILUREAuthentication failed for the requestThe 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_PROGRESSThere is a hotel currency switch currently in progressYou need to wait until hotel switch currency.
DATE_ELEMENT_MISSINGDate is missingDate is required for this request.
EXCEEDS_MAX_RELATIVE_RELEASE_TIMERelative 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_DATEFrom date should be less than or equal To DateThe From date should be less than or equal to the To date.
HOTEL_ACCESS_DENIEDRequest 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_UFIThe timezone value is missing for the Ufi associated with hotel ID $hotel_idCheck the property's UFI configuration.
INTERNAL_SERVER_ERRORInternal server errorBooking.com service failed.
NOT_A_VALID_DATEINVALID_DATEThe 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_TIMERelease 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_EXTRANETRate '%s' is only editable on ExtranetYou are not allowed to edit the rate via the connectivity API. The property can edit the rate via the Booking.com extranet.
RATE_ID_REQUIREDRate Id is requiredRate id is required for this request.
RATE_IS_A_SLAVE_RATEYou cannot set $attribute for a child rate $rate_id, since they are automatically set based on Rate RelationsCannot update a child rate.
RATE_NOT_ACTIVE_FOR_ROOMRate '%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_EXTRANETRoom '%s' is only editable on ExtranetYou are not allowed to edit the room via the connectivity API. The property can edit the room via Booking.com extranet.
ROOM_ELEMENT_REQUIREDRoom is missingThe request contains an empty request body.
ROOM_ID_INVALIDRoom ID '%s' is not validProvide a valid Room ID. Make sure to retrieve the correct Room ID using the [rooms endpoint][retrieving-room-types].
ROOM_ID_MISSINGRoom ID is missingRoom ID is required for the request.
TYPE_VIOLATIONGeneric 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] -->