# 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 | Attribute | 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


```xml
<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](/connectivity/docs/pricing-models#derived-pricing-type), [OBP](/connectivity/docs/pricing-models#occupancy-based-pricing-obp) or [LOS](/connectivity/docs/pricing-models#length-of-stay-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](/connectivity/docs/pricing-models#occupancy-based-pricing-obp), then this price relates to the level of occupancy specified in the `occupancy` attribute.If the pricing model is [LOS](/connectivity/docs/pricing-models#length-of-stay-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](/connectivity/docs/pricing-models#standard-model-also-known-as-default-pricing) pricing model |


### Response examples

#### Success Response example (`room_level` = `1`)


```xml
<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`)


```xml
<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
<?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](/connectivity/docs/room-type-and-rate-plan-management/managing-room-types/#retrieving-active-room-types) 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. |