Last updated

Retrieve inventory and rate details

The xml/roomrateavailability endpoint returns inventory information per property from Booking.com.

The response contains the following information:

  • Room, rate and date information.
  • Number of booked rooms.
  • Number of cancelled rooms.
  • Whether a room and rate combination is closed for a certain date.
  • Only available in v1.1 Whether a room type is closed. When a room type is closed, 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.
  • Number of minimum contracted rooms for a room and rate combination per date.
  • Number of minimum contracted rooms for a room and rate combination per date.
  • Number of rooms left to sell.

HTTP Request

POST https://supply-xml.booking.com/hotels/xml/roomrateavailability

Difference between roomrateavailability endpoint v1.0 and v1.1

The roomrateavailability endpoint has two versions currently. When migrating to the v1.1 roomrateavailability endpoint, you can view whether a room type is closed.

For an update on the changes, see the migration guide.

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: New version.
- 1.0: Previous version.

Sample header

POST 'https://supply-xml.booking.com/hotels/xml/availability' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblhWTdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'

Request body parameters

FieldDescriptionTypeRequiredNotes
requestRoot element.objectRequired-
__ >__ hotel_idThe property for which you want to retrieve availability.IDRequired-
__ >__ versionInterface specification version.floatOptionalDefault: 1.0
__ >__ number_of_daysReturns N rows starting from the date specified in the start_date (inclusive), where N is the number_of_days value. If the start_date is not provided, then the API returns inventory information from the next day of the request till the number_of_days value.integerOptionalMin/max value: 1/31
By default, the API returns 31 days of inventory information.
Any value less than 1 or greater than 31 returns an error.
__ >__ start_dateThe date from which you want to retrieve availability information.datetimeOptionalFormat: YYYY-MM-DD
If the start_date is not provided, then the API returns inventory information from the next day of the request till the number_of_days value.
__ >__ room_levelIndicates whether you want to retrieve information at the room level or rate level.integerOptionalBoolean expressed as integer.
0 = rate level (default)
1 = room level
__ >__ room_idFilter results by room ID.integerOptionalBy default, returns inventories for all rooms.

Request body example

<request>
  <hotel_id>367456</hotel_id>
  <version>1.0</version>
  <number_of_days>2</number_of_days>
  <start_date>2023-09-19</start_date>
  <room_level>1</room_level>
  <room_id>12302</room_id>
</request>

Response body example (room_level = 1)

<result>
  <room room_id="26551401">
    <date
      min_contracted_rooms="0"
      min_contracted_rooms_until="0"
      rooms_to_sell="0"
      value="2017-09-01"  
      closed="0">
      <rate
        booked="0"
        cancelled="0"
        closed="1"
        closed_on_arrival="0"
        closed_on_depart="0"
        exact_stay_arrival="0"
        length_of_stay="0"
        max_advance_res=""
        max_stay_arrival="0"
        max_stay_through="0"
        min_advance_res=""
        min_contracted_rooms="0"
        min_contracted_rooms_until="0"
        min_stay_arrival="0"
        min_stay_through="0"
        occupancy="2"
        policygroup=""
        price="35.00"
        price_single="35.00"
        rate_id="910013"/>
    </date>
  </room>
  <warnings>
        <warning>We excluded the following rooms from the result, because they have no room-level availability and the request contained room_level=1. room_ids: 12301, 12303</warning>
  </warnings>
</result>

Notes:

  • Booking.com generally handles availability at room level. If you request availability information at rate level for a property with a room level inventory, the response is likely to be inaccurate.
  • If you specify room_level=1, then the API ignores rooms that have no room-level availability. See the warning in the sample above.
  • If you specify room_level=0, then the API ignores room-level closure information.

Response body example (room_level = 0)

<result>
    <roomrate
      booked="0"
      cancelled="0"
      closed="0"
      date="2023-09-19"
      rate_id="12345678"
      room_id="12302"
      rooms_to_sell="2"/>
    <!-- More <roomrate> elements would follow here. Skipped for brevity. -->
</result>
<!-- RUID: [UmFuZG9tSVYkc2RlIyetc] -->

Response body elements

Default values

For integer-type attributes, the default value is 0. For non-integer attributes, the default is an empty string.

ElementAttributeDescriptionTypeNotes
resultRoot element.objectChildren will be either roomrate or a combination of room and rate elements, depending on the value of room_level in the request.
> roomContains availability information for the specified room.objectThe API returns this element only if the value of room_level in the request is 0.
room_idThe room for which information is being shown.integer-
> dateContains availability information for specified date.objectThe API returns this element only if the value of room_level in the request is 0.
valueThe date from which availability is being shown.datetimeFormat: YYYY-MM-DD
rooms_to_sellThe number of available rooms left for the specified room, rate and date combination.integer-
closed[Only available for the v1.1] Specifies whether all rooms of a room type are closed (not bookable) on the specified date.booleanPossible values are: 1 (closed), 0 (open).

Once you close a room, make sure to open it before setting availability for it.
> roomrateContains availability information for specified room, rate and date combination.objectThe API returns this element only if the value of room_level in the request is 0. See the table below for a list of supported attributes.
> rateContains availability information for specified rate.objectThe API returns this element only if the value of room_level in the request is 1. See the table below for a list of supported attributes.

The following attributes are applicable for both roomrate and rate elements.

ElementAttributeDescriptionTypeNotes
> roomrate/rateContains availability information.objectsThe following attributes are applicable for both the elements.
bookedThe number of booked rooms for the specified room, rate and date combination.integer-
cancelledThe number of cancelled rooms for the specified room, rate and date combination.integer-
closedIndicates whether the room, rate and date combination is closed for sales or open bookable.integerBoolean expressed as integer. 1 = true, 0 = false.
rate_idThe rate for which information is being shown.integer-
dateThe date from which availability is being shown.datetimeFormat: YYYY-MM-DD
room_idThe room for which information is being shown.integer-
rooms_to_sellThe number of available rooms left for the specified room, rate and date combination.integer-
closed_on_arrivalSpecifies in a boolean value whether it's possible to check in for room, rate and date combination.boolean
closed_on_departSpecifies in a boolean value whether it's possible to check out for the room, rate and date combination.boolean
exact_stay_arrivalStay length needs to have exactly that value, checked on arrival day.integer
length_of_stayThis is the FPLOS (Full Pattern Length of Stay restriction). This is only relevant to providers who have the FPLOS settings enabled.binaryBinary representation of length of stay where 0 means there are no constraints and 1 means no checkout at this date - string of length 32. If there are 3 dots at the end, then this means repeat the last bit till the length of the string is 32. For example 1001... means 10011111111111111111111111111111.
min_stay_arrivalMinimum length of stay, checked on arrival day.integer
max_stay_arrivalMaximum length of stay, checked on arrival day.integer
min_stay_throughMinimum length of stay of any reservation that overlaps this date.integer
max_stay_throughMaximum length of stay of any reservation that overlaps this date.integer
min_advance_resMinimum time before the check in date when the booking can be made. Follows the format XDYH where X is the number of days and Y is the number of hours.stringX and Y are integers. XDYH is a fixed format string. The values used when setting max_advance_res or min_advance_res using the availability APIs are recalculated to the nearest day value.
For example, if you set max_advance_res to 25H, while retrieving roomrate details, the endpoint returns 1D1H. The search date is counted as one of the days in the restriction length.
max_advance_resMaximum time before the check in date when the booking can be made. Follows the format XDYH where X is the number of days and Y is the number of hours.stringX and Y are integers. XDYH is a fixed format string. The values used when setting max_advance_res or min_advance_res using the availability APIs are recalculated to the nearest day value.
For example, if you set max_advance_res to 25H, while retrieving roomrate details, the endpoint returns 1D1H. The search date is counted as one of the days in the restriction length.
occupancyThe number of guests in a room under a particular room rate.integerYou can only access and use this attribute when the property opted for the OBP or LOS pricing model.
policygroupContains the policy group name.integer
priceThe monetary value per night for the maximum occupancy of a room under a particular room rate.doubleThis price is dependent on the currency, which is set in the Booking.com system.
If the pricing model is OBP, then this price relates to the level of occupancy specified in the occupancy attribute.
If the pricing model is LOS, then you receive a list of comma-separated prices. Each price corresponds to a length of stay ( 1 night, 2 nights, ...) with the level of occupancy specified in the occupancy attribute.
price_singleThe room rate for 1 person per night depending on the currency of the property set in the Booking.com system.double

HTTP error list

If the request returns an error, the xml/roomrateavailability endpoint returns an error description with the fault code=400. The following table captures all the error validations and their possible resolutions.

Error messageNotes
Room ID '%s' is not validIncorrect room ID. Make sure to retrieve the correct room ID using the rooms endpoint and specify under room_id.
Number of days should be between [1 - 31]Make sure to specify a value between 1 and 31 for the number_of_days parameter.
Required parameter 'hotel_id' not providedThe request is missing the mandatory parameter hotel_id.
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.
Date '2040-03-18' is past last allowed date '2033-12-31'You can specify a date that is up to 10 years in the future.

Warning

Warning messageNotes
We excluded the following rooms from the result, because they have no room-level availability and the request contained room_level=1. room_ids: '%s'When querying for room-level availability, if the API doesn't find room-level availability for certain rooms, it omits them in the response.