Retrieve inventory and rate details

Use the roomrateavailability endpoint to retrieve inventory information per property from Booking.com for all active room/rate (products) combinations

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
Whether a room type is closed (when 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 rooms left to sell

Endpoint

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

Request

Headers

Header	Description	Type	Required	Notes
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	Optional	Supports the following values: - 1.1: Default version.

Request body

Element	Description	Type	Required	Notes
`request`	Root element.	object	Required	-
> `hotel_id`	The property for which you want to retrieve availability.	integer	Required	-
> `number_of_days`	Returns 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.	integer	Optional	Min/max value: `1`/`31` By default, the API returns 31 days of inventory information.
> `start_date`	The date from which you want to retrieve availability information.	datetime	Optional	Format: `YYYY-MM-DD`. Supports dates from 1 day in the past (follows Central European Time (CET) timezone) and up to 5 years in future. 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_level`	Indicates whether you want to retrieve information at the room level or rate level.	integer	Optional	Boolean expressed as integer. `0` = rate level (default) `1` = room level
> `room_id`	Filter results by room ID.	integer	Optional	By default, returns inventories for all rooms.

Request example

<request>
  <hotel_id>12345</hotel_id>
  <version>1.1</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>

Room level vs. rate level availability

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 response example.
If you specify room_level=0, then the API ignores room-level closure information.

Response

Response body

Default values

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

Element	Attribute	Description	Type	Notes
`result`		Root element.	object	Children will be either `roomrate` or a combination of `room` and `rate` elements, depending on the value of `room_level` in the request.
> `room`		Contains availability information for the specified room.	object	The API returns this element only if the value of `room_level` in the request is `1`.
	`room_id`	The room for which information is being shown.	integer	-
>> `date`		Contains availability information for specified date.	object	The API returns this element only if the value of `room_level` in the request is `1`.
	`value`	The date from which availability is being shown.	datetime	Format: `YYYY-MM-DD`
	`rooms_to_sell`	The number of available rooms left for the specified room, rate and date combination.	integer	-
	`min_contracted_rooms`	The minimum number of contracted rooms for the specified room and date.	integer	-
	`min_contracted_rooms_until`	The minimum number of contracted rooms until a specific date.	integer	-
	`closed`	Specifies whether all rooms of a room type are closed (not bookable) on the specified date.	boolean	Accepts: `1` (closed), `0` (open).
>>> `rate`		Contains availability information for specified rate.	object	The API returns this element only if the value of `room_level` in the request is `1`. See the common attributes table below.
> `roomrate`		Contains availability information for specified room, rate and date combination.	object	The API returns this element only if the value of `room_level` in the request is `0`. See the common attributes table below.
> `warnings`		Groups a list of individual warnings.	object	-
>> `warning`		Returns a user-friendly warning message.	string	-

Common attributes for `rate` and `roomrate` elements

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

Attribute	Description	Type	Notes
`rate_id`	Booking.com rate plan ID.	integer	-
`room_id`	Booking.com room ID.	integer	Only applicable for `roomrate` element.
`date`	The date from which availability is being shown.	datetime	Format: `YYYY-MM-DD` Only applicable for `roomrate` element.
`booked`	The number of booked rooms for the specified room, rate and date combination.	integer	-
`cancelled`	The number of cancelled rooms for the specified room, rate and date combination.	integer	-
`closed`	Indicates whether the room, rate and date combination is closed for sales or open bookable.	integer	Boolean expressed as integer. `1` = closed, `0` = open.
`rooms_to_sell`	The number of available rooms left for the specified room, rate and date combination.	integer	-
`closed_on_arrival`	Specifies whether it's possible to check in for room, rate and date combination.	boolean	`1` = closed, `0` = open.
`closed_on_depart`	Specifies whether it's possible to check out for the room, rate and date combination.	boolean	`1` = closed, `0` = open.
`exact_stay_arrival`	Stay length needs to have exactly that value, checked on arrival day.	integer	-
`length_of_stay`	The FPLOS (Full Pattern Length of Stay restriction). This is only relevant to providers who have the `FPLOS` settings enabled.	binary	Binary 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_arrival`	Minimum length of stay, checked on arrival day.	integer	-
`max_stay_arrival`	Maximum length of stay, checked on arrival day.	integer	-
`min_stay_through`	Minimum length of stay of any reservation that overlaps this date.	integer	-
`max_stay_through`	Maximum length of stay of any reservation that overlaps this date.	integer	-
`min_advance_res`	The minimum number of days and/or hours that guests must book in advance (before the planned stay date at 24:00 in the hotel timezone).	string	Format: `XDYH` where X is the number of days and Y is the number of hours. The values used when setting `min_advance_res` using the `availability` APIs are recalculated to the nearest day value. For example, if you set `min_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_res`	The maximum number of days and/or hours that guests must book in advance (before the planned stay date at 24:00 in the hotel timezone).	string	Format: `XDYH` where X is the number of days and Y is the number of hours. The values used when setting `max_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.
`min_contracted_rooms`	The minimum number of contracted rooms for the specified room, rate and date.	integer	Only applicable for `rate` element.
`min_contracted_rooms_until`	The minimum number of contracted rooms until a specific date.	integer	Only applicable for `rate` element.
`occupancy`	The number of guests in a room under a particular room rate.	integer	You can only access and use this attribute when the property opted for the RLO, OBP or LOS pricing model.
`policygroup`	Contains the policy group name.	string	-
`price`	The monetary value per night for the maximum occupancy of a room under a particular room rate.	float	This 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_single`	The price for 1 person per night depending on the currency of the property set in the Booking.com system.	float	You can only access and use this attribute when the room-rate is on the Standard pricing model

Response examples

Success Response 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>
<!-- RUID: [Example-RUID] -->

Success Response 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: [Example-RUID] -->

Error response (HTTP 400)

<?xml version='1.0' encoding='UTF-8'?>
<roomrateavailability>
  <fault code="400">
    <string>Room ID '1234' is not valid</string>
  </fault>
</roomrateavailability>
<!-- RUID: [Example-RUID] -->

Troubleshooting errors

This section covers the error and warning responses you might encounter when using this endpoint.

Error responses

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

Error message	Description
Room ID '%s' is not valid	Incorrect 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 provided	The 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 have enough permissions.
Date '2040-03-18' is past last allowed date '2033-12-31'	You can specify a date that is up to 5 years in the future.

Warnings

Warning message	Description
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.