# Managing units

Use this endpoint to create units, add rooms, add bed configurations, set occupancy, among other tasks.

You can:

- [create units](#creating-a-unit) ([why units instead of rooms?](/connectivity/docs/rooms-api/introduction-to-rooms-api#understanding-rooms-api-terminology))
- [update units](#updating-a-unit)
- [delete units](#deleting-a-unit)
- [retrieve units](#retrieving-units)
- [retrieve previously deleted units](#retrieving-deleted-units)


## Before you start

Before implementing the Rooms API, it is important to explore the relevant metadata and validation rules.

### Discover relevant meta information

To create a unit, you must provide the unit type ID, unit name ID, and bed type ID. For example, to create an Apartment with a Sea view and with a large bed, you must specify the following IDs:

- unit type ID `1` refers to Apartment
- unit name ID `44` refers to Apartment with Sea View
- bed type ID `6` refers to Large bed


You can find the IDs and their corresponding attributes using the Rooms API meta endpoint. For more information, see the [Retrieving units metadata details](/connectivity/docs/rooms-api/rooms-api-meta-information) and the corresponding [OpenAPI specification.](/connectivity/docs/openapispecs/rooms-api/rooms-api-specification/rooms-api)

Each unit type object has a set of important attributes:

- `is_active` - defines if a unit type can be used to create or update units. Inactive unit types are read-only.
- `allowed_property_categories` - defines a set of property categories for which a given unit type can be created, and
- `is_multi_room` - defines if a unit type is a single or multi-room.


### Understand the difference between single and multi-room units

The Rooms API supports two categories of units:

- single-room
- multi-room


The following table summarizes the differences between single-room unit and multi-room units:

| Category | Example unit types | Supports creating multiple rooms? | Supported room types | Supports multiple bed configurations? |
|  --- | --- | --- | --- | --- |
| Single-room unit | `Studio`, `Double` | no | `GUEST_ROOM` | yes |
| Multi-room unit | `Apartment`, `Villa`, `Suite` | yes | `BEDROOM_SUBROOM`, `LIVING_ROOM_SUBROOM` | no |


To add a kitchen or a kitchenette to a multi-room unit, use the [Facilities API](/connectivity/docs/content-api-modules/facilities-api/manage-room-facilities) and specify the `room_facility_id`: 23 (`KITCHEN`) or `room_facility_id`: 24 (`KITCHENETTE`).

Note that each category has distinct validation requirements. For more information, see:

- [Validation rules specific to single-room units](/connectivity/docs/rooms-api/rooms-api-validations#validation-rules-specific-to-single-room-units)
- [Validation rules specific to multi-room units](/connectivity/docs/rooms-api/rooms-api-validations#validation-rules-specific-to-multi-room-units)


### Learn more about the create and update requests validations

The request body for POST and PATCH requests is validated against a [set of rules](/connectivity/docs/rooms-api/rooms-api-validations#rooms-api-validation-rules). These include generic rules applicable to all units, as well as specific rules based on unit category (single- or multi-room) and unit type.

### Understand the occupancy model

Occupancy defines how the number of guests is calculated. Occupancy has implications when defining children rates and availability.

You specify the following fields within the `occupancy_details` request body parameter:

- maximum number of guests (`max_guests`)
- maximum  adult occupancy(`max_adults`)
- maximum occupancy by children (3-17 years old) (`max_children`)
- maximum occupancy by infants (0-2 years old) (`max_infants`) when you want to count infant occupancy toward the maximum number of guests
- maximum occupancy by infants (0-2 years old) on top of maximum number of guests (`max_infants_on_top`) when you want to count infant occupancy separately from the maximum number of guests


Note that values of `max_infants` or `max_infants_on_top` are mutually exclusive - only one can be non-zero at a time, while the other one must always be zero.

#### Migration guide for connectivity providers that implemented Rooms API before 5 June 2025

Before 5 June 2025 Rooms API offered a simpler occupancy model. You specified the following fields within the `occupancy` request body parameter:

- maximum number of guests (`max_guests`)
- maximum adult occupancy(`max_adults`)
- maximum occupancy by children 0-17 years old (`max_children`)


Booking.com plans to deprecate the old occupancy model, making migration to the new model mandatory. A deprecation announcement with the exact timeline will follow soon.

To ensure compatibility with existing implementations, Booking.com has added a provider feature called `rooms_api_old_occupancy_enabled` and enabled it on your behalf. While the feature is turned on, you can still read and write `occupancy` as before.

To prepare for migration, you may use another provider feature called `rooms_api_new_occupancy_forced`. This allows you to test the updated `occupancy_details` field on a per-request basis. Find more about using provider features in test requests on the [Provider Portal](https://connect.booking.com/feature_management) in the *How to Test* section.

When ready, disable the `rooms_api_old_occupancy_enabled` feature in order to start using the new occupancy model in all your requests and complete the migration.

## Creating a unit


```http
POST
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/units
```

### Header parameter

The following table describes the elements you can add in the header:

| Header | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Content-Type: application/json` | Specifies the expected content type. | string | required |  |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | optional | Currently supports the value:  1.0 |


### Path parameters

The following table describes the elements you must specify in the path:

| Element | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `propertyId` | Specifies the unique ID of the property. | integer | required | Must be valid and assigned to your account |


### Request body parameters

The following table describes the elements you can add in the request body:

| Element | Description | Type | Required/Optional | Default value | Root parameter in HIN |
|  --- | --- | --- | --- | --- | --- |
| `unit_name_id` | Specifies the unit name ID that is part of the unit type | string | required | n/a | `Description > Text` |
| `number_of_units` | Specifies the total number of units available at the property | integer | optional | `1` | `Room > Quantity` |
| `smoking_policy` | Specifies the smoking policy in the unit | enumerated string | optional | `SMOKING_AND_NONSMOKING` | `Room > NonSmoking` |
| `size` | Contains the unit size details | object | optional | `null` |  |
| **>** `value` | Specifies the unit size in the chosen unit | integer | required1 | n/a | `Room > SizeMeasurement` |
| **>** `unit` | Specifies the unit of measurement to represent the unit size | enumerated string | required1 | n/a | `Room > SizeMeasurementUnit` |
| `partner_reference_name` | Specifies a custom unit name visible in the extranet and API response | string | optional | `null` | New field |
| `floor_numbers_located_on` | Specifies the floor where the unit is located | array of integer(s) | optional | `null` | New field |
| `configuration` | Contains the unit configuration | object | required | n/a |  |
| **>** `unit_type_id` | Specifies the unit type ID | enumerated string | required | n/a | `Room > RoomType` |
| **>** `rooms` | Contains the room details provided the unit type supports rooms | array of objects | required | n/a |  |
| **>>** `type` | Specifies the room type supported by the unit type | enumerated string | required | n/a | `SubRoom > RoomType` |
| **>>** `bed_configurations` | Contains the details of the bed available in the room | object | conditional2 | n/a | `SubRoom > Amenities` |
| **>>>** `beds` | Contains the bed type and the total number of beds | array of objects | required1 | n/a |  |
| **>>>>** `bed_type_id` | Specifies the bed type ID supported by the unit type | enumerated integer | required1 | n/a | `AmenityCode (or RoomAmenityCode)` |
| **>>>>** `bed_count` | Specifies the total number of beds of the type specified above | integer | required1 | n/a | `Quantity (or Value)` |
| **>>>** `is_default_configuration` | Specifies whether the specified bed configuration is default for the unit/room | boolean | required1 | n/a | `Configuration` |
| `occupancy_details`3 | Contains the occupancy details of the unit | object | optional | n/a | - |
| **>** `max_guests` | Specifies the maximum guest occupancy for the unit | integer | optional | `1` | `Occupancy > MaxOccupancy` |
| **>** `max_adults` | Specifies the maximum adult occupancy for the unit | integer | optional | `1` | `Occupancy > MaxAdultOccupancy` |
| **>** `max_children` | Specifies the maximum occupancy of children (ages 3-17) per unit. | integer | optional | `0` | New field. If this value is set to `0` for all units, then the `allow_children` property setting is set to `false` and all children policy rules are deleted, including the `price` details. See [Property settings](/connectivity/docs/content-api-modules/property-details-api/implementing-property-api-settings#childrenpolicies) for more information. |
| **>** `max_infants` | Specifies the maximum infants (0-2) occupancy for the unit count toward `max_guests` | integer | optional | `max_children` | New field |
| **>** `max_infants_on_top` | Specifies the maximum infants (0-2) occupancy for the unit on top of `max_guests` | integer | optional | `0` | New field |
| `max_children_that_pay_children_rate` | Specifies the maximum number of children eligible for the children rate. Note that infants will always pay [children rate](/connectivity/docs/flexible-children-rates/managing-flexible-children-rates) if it is available, irrespective of the limit set here. | integer | optional | `max_children` | `TPA_Extensions > MaxChildPayableOccupancy` |
| `extra_beds_configuration` | Contains the extra beds details for the unit | object | optional | n/a |  |
| **>** `extra_beds` | Specifies the total number of extra beds available on request per unit/room | integer | optional | `0` | `Quantities > MaxRollaways` |
| **>** `cribs` | Specifies the total number of extra cribs available on request per unit/room | integer | optional | `0` | `Quantities > MaxCribs` |
| **>** `is_crib_and_extra_bed_allowed` | Specifies whether guests can request both the extra bed and crib in the unit/room | boolean | optional | `false` | New field |


1 - required only if a parent field is provided
2 - required for room types `GUEST_ROOM` and `BEDROOM_SUBROOM`. Optional for `LIVING_ROOM_SUBROOM`
3 - if the provider feature: `rooms_api_old_occupancy_enabled` is enabled, you see `occupancy` containing only `max_guests`, `max_adults` and `max_children`. For more details, see the [Migration guide](#migration-guide-for-connectivity-providers-that-implemented-rooms-api-before-5-june-2025).

### Request body example

For example, the following request creates a multi-room unit with two bedrooms and one living room:

{
  "configuration": {
    "unit_type_id": 1,
    "rooms": [
      {
        "type": "BEDROOM_SUBROOM",
        "bed_configurations": [
          {
            "beds": [
              {
                "bed_type_id": 6,
                "bed_count": 1
              }
            ],
            "is_default_configuration": true
          }
        ]
      },
      {
        "type": "BEDROOM_SUBROOM",
        "bed_configurations": [
          {
            "beds": [
              {
                "bed_type_id": 4,
                "bed_count": 1
              }
            ],
            "is_default_configuration": true
          }
        ]
      },
      {
        "type": "LIVING_ROOM_SUBROOM",
        "bed_configurations": [
          {
            "beds": [
              {
                "bed_type_id": 7,
                "bed_count": 1
              }
            ],
            "is_default_configuration": true
          }
        ]
      }
    ]
  },
  "unit_name_id": 138547,
  "number_of_units": 5,
  "smoking_policy": "SMOKING_AND_NONSMOKING",
  "size": {
    "value": 155.0,
    "unit": "SQM"
  },
  "partner_reference_name": "Park facing Apartment",
  "floor_numbers_located_on": [
    2
  ],
  "occupancy_details": {
    "max_guests": 5,
    "max_adults": 5,
    "max_children": 4,
    "max_infants": 4,
    "max_infants_on_top: 0"
  },
  "max_children_that_pay_children_rate": 2,
  "extra_beds_configuration": {
    "extra_beds": 1,
    "cribs": 0,
    "is_crib_and_extra_bed_allowed": false
  }
}
For more request examples for various use cases, see the examples in the API Explorer section in the [Open API specification.](/connectivity/docs/openapispecs/rooms-api/rooms-api-specification/rooms-api/createunit)

### Response body example

The following is a response snippet:

{
  "data": {
    "unit_id": 813518812,
    "configuration": {
      "unit_type_id": 1,
      "rooms": [
        {
          "type": "BEDROOM_SUBROOM",
          "bed_configurations": [
            {
              "beds": [
                {
                  "bed_type_id": 6,
                  "bed_count": 1
                }
              ],
              "is_default_configuration": true
            }
          ]
        },
        {
          "type": "BEDROOM_SUBROOM",
          "bed_configurations": [
            {
              "beds": [
                {
                  "bed_type_id": 4,
                  "bed_count": 1
                }
              ],
              "is_default_configuration": true
            }
          ]
        },
        {
          "type": "LIVING_ROOM_SUBROOM",
          "bed_configurations": [
            {
              "beds": [
                {
                  "bed_type_id": 7,
                  "bed_count": 1
                }
              ],
              "is_default_configuration": true
            }
          ]
        }
      ]
    },
    "unit_name_id": 138547,
    "number_of_units": 5,
    "smoking_policy": "SMOKING_AND_NONSMOKING",
    "size": {
      "value": 155.0,
      "unit": "SQM"
    },
    "partner_reference_name": "Park facing Apartment",
    "floor_numbers_located_on": [
      2
    ],
    "occupancy_details": {
      "max_guests": 5,
      "max_adults": 5,
      "max_children": 4,
      "max_infants": 4,
      "max_infants_on_top": 0
    },
    "max_children_that_pay_children_rate": 2,
    "extra_beds_configuration": {
      "extra_beds": 1,
      "cribs": 0,
      "is_crib_and_extra_bed_allowed": false
    }
  },
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}
### Response body elements

The following table describes the response elements:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `data` | Contains details of the unit created. | object | - |
| **>** `unit_id` | Specifies the unit ID | string | - |
| **>** `configuration` | Contains the unit configuration | object | - |
| **>>** `unit_type_id` | Specifies the unit type ID | enumerated string | - |
| **>>** `rooms` | Contains the room details provided the unit type supports rooms (also known as subrooms) | array of objects | - |
| **>>>** `type` | Specifies the room type supported by the unit type | enumerated string | - |
| **>>>** `bed_configurations` | Contains the details of the bed available in the room | object | - |
| **>>>>** `beds` | Contains the bed type and the total number of beds | array of objects | - |
| **>>>>>** `bed_type_id` | Specifies the bed type ID that is supported by the unit type | enumerated integer | - |
| **>>>>>** `bed_count` | Specifies the total number of beds available in the unit/room | integer | - |
| **>>>>** `is_default_configuration` | Specifies whether the specified bed configuration is default for the unit/room | boolean | - |
| **>** `unit_name_id` | Specifies the unit name ID that is part of the unit type | string | - |
| **>** `number_of_units` | Specifies the total number of rooms available at the property for the specified room type | integer | - |
| **>** `smoking_policy` | Specifies the smoking policy in the room | enumerated string | - |
| **>>** `size` | Contains the unit size details | object | - |
| **>>>** `value` | Specifies the unit size in the chosen unit | integer | - |
| **>>>** `unit` | Specifies the unit of measurement to represent the unit size | enumerated string | - |
| **>** `partner_reference_name` | Specifies a custom unit name that is visible in the extranet and in the API response | string | - |
| **>** `floor_numbers_located_on` | Specifies the floor where the unit is located | array of integer(s) | - |
| **>** `occupancy_details`1 | Contains the occupancy details of the unit | object | - |
| **>>** `max_guests` | Specifies the maximum guest occupancy for the unit | integer | - |
| **>>** `max_adults` | Specifies the maximum adult occupancy for the unit | integer | - |
| **>>** `max_children` | Specifies the maximum occupancy of children (ages 3-17) per unit. | integer | - |
| **>>** `max_infants` | Specifies the maximum infants (0-2) occupancy for the unit count toward `max_guests` | integer | - |
| **>>** `max_infants_on_top` | Specifies the maximum infants (0-2) occupancy for the unit on top of `max_guests` | integer | - |
| `max_children_that_pay_children_rate` | Specifies the maximum number of children eligible for the child rate | integer | - |
| **>** `extra_beds_configuration` | Contains the extra beds details for the unit | object | - |
| **>>** `extra_beds` | Specifies the total number of extra beds available on request per room/unit | integer | - |
| **>>** `cribs` | Specifies the total number of extra cribs available on request per room/unit | integer | - |
| **>>** `is_crib_and_extra_bed_allowed` | Specifies whether guests have the option of requesting both the extra bet and crib in the room/unit | boolean | - |
| `warnings` | Contains any warnings in the request | object | - |
| `errors` | Contains any errors in the request | object | - |
| `meta` | Contains metadata information about the response | object | - |
| **>** `ruid` | Specifies the unique request ID | string | You can share this ID with Booking.com customer support when you run into an issue This can help in understanding what went wrong |


1 - if the provider feature: `rooms_api_old_occupancy_enabled` is enabled, you see `occupancy` containing only `max_guests`, `max_adults` and `max_children`. For more details, see the [Migration guide](#migration-guide-for-connectivity-providers-that-implemented-rooms-api-before-5-june-2025).

## Updating a unit


```http
PATCH
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/units/{unitID}
```

To update an existing unit, copy the relevant portion of the response from the [GET property unit details](#retrieving-unit-details) endpoint and use it as the request body.
As an update action, the API overlays the existing unit details with the configuration in the request body.
Make sure to send the root-level field and their nested fields.

Note that updating a unit doesn't affect existing reservations.

### Header parameter

The following table describes the elements you can add in the header:

| Header | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Content-Type: application/json` | Specifies the expected content type. | string | required |  |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | optional | Currently supports the value:  1.0 |


### Path parameters

The following table describes the elements you must specify in the path:

| Element | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `propertyId` | Specifies the unique ID of the property. | integer | required | Must be valid and connected to your account |
| `unitID` | Specifies the unique ID of the unit to update. | integer | required | Must belong to the property |


### Request body parameters

The following table describes the elements you can add in the request body. Note that every root level field is optional, but if it has subfields you must provide all the subfields in full.

| Element | Description | Type | Required/Optional | Root parameter in HIN |
|  --- | --- | --- | --- | --- |
| `unit_name_id` | Specifies the unit name ID that is part of the unit type | string | optional | `Description > Text` |
| `number_of_units` | Specifies the total number of units available at the property | integer | optional | `Room > Quantity` |
| `smoking_policy` | Specifies the smoking policy in the unit | enumerated string | optional | `Room > NonSmoking` |
| `size` | Contains the unit size details | object | optional |  |
| **>** `value` | Specifies the unit size in the chosen unit | integer | required1 | `Room > SizeMeasurement` |
| **>** `unit` | Specifies the unit of measurement to represent the unit size | enumerated string | required1 | `Room > SizeMeasurementUnit` |
| `partner_reference_name` | Specifies a custom reference name visible in the extranet and API response | string | optional | New field |
| `floor_numbers_located_on` | Specifies the floor where the unit is located | array of integer(s) | optional | New field |
| `configuration` | Contains the unit configuration | object | optional |  |
| **>** `unit_type_id` | Specifies the unit type ID | enumerated string | required1 | `Room > RoomType` |
| **>** `rooms` | Contains the room details provided the unit type supports rooms | array of objects | required1 |  |
| **>>** `type` | Specifies the room type supported by the unit type | enumerated string | required1 | `SubRoom > RoomType` |
| **>>** `bed_configurations` | Contains the details of the bed available in the room | object | conditional2 | `SubRoom > Amenities` |
| **>>>** `beds` | Contains the bed type and the total number of beds | array of objects | required1 |  |
| **>>>>** `bed_type_id` | Specifies the bed type ID supported by the unit type | enumerated integer | required1 | `AmenityCode (or RoomAmenityCode)` |
| **>>>>** `bed_count` | Specifies the total number of beds of the type specified above | integer | required1 | `Quantity (or Value)` |
| **>>>** `is_default_configuration` | Specifies whether the specified bed configuration is default for the unit/room | boolean | required1 | `Configuration` |
| `occupancy_details`3 | Contains the occupancy details of the unit | object | optional | - |
| **>** `max_guests` | Specifies the maximum guest occupancy for the unit | integer | required1 | `Occupancy > MaxOccupancy` |
| **>** `max_adults` | Specifies the maximum adult occupancy for the unit | integer | required1 | `Occupancy > MaxAdultOccupancy` |
| **>** `max_children` | Specifies the maximum occupancy of children (ages 3-17) per unit | integer | required1 | New field. If this value is set to `0` for all units, then the `allow_children` property setting is set to `false` and all children policy rules are deleted, including the `price` details. See [Property settings](/connectivity/docs/content-api-modules/property-details-api/implementing-property-api-settings#childrenpolicies) for more information. |
| **>** `max_infants` | Specifies the maximum infants (0-2) occupancy for the unit count toward `max_guests` | integer | required1 | n/a |
| **>** `max_infants_on_top` | Specifies the maximum infants (0-2) occupancy for the unit on top of `max_guests` | integer | required1 | n/a |
| `max_children_that_pay_children_rate` | Specifies the maximum number of children eligible for the child rate | integer | optional | `TPA_Extensions > MaxChildPayableOccupancy` |
| `extra_beds_configuration` | Contains the extra beds details for the unit | object | optional |  |
| **>** `extra_beds` | Specifies the total number of extra beds available on request per unit/room | integer | required1 | `Quantities > MaxRollaways` |
| **>** `cribs` | Specifies the total number of extra cribs available on request per unit/room | integer | required1 | `Quantities > MaxCribs` |
| **>** `is_crib_and_extra_bed_allowed` | Specifies whether guests can request both the extra bed and crib in the unit/room | boolean | required1 | New field |


1 - required only if a parent field is provided 
2 - required for room types `GUEST_ROOM` and `BEDROOM_SUBROOM`, optional for `LIVING_ROOM_SUBROOM` 
3 - if the provider feature: `rooms_api_old_occupancy_enabled` is enabled, you see `occupancy` containing only `max_guests`, `max_adults` and `max_children`. For more details, see the [Migration guide](#migration-guide-for-connectivity-providers-that-implemented-rooms-api-before-5-june-2025).

### Request body example

For example, the following request sets new smoking policy, size and occupancy for an existing unit:

{
  "smoking_policy": "SMOKING",
  "size": {
      "value": 45.0,
      "unit": "SQM"
  },
  "occupancy_details": {
      "max_guests": 3,
      "max_adults": 3,
      "max_children": 2,
      "max_infants": 0,
      "max_infants_on_top": 3
  }
}
For more request examples for various use cases, see the examples in the API Explorer section in the [Open API specification.](/connectivity/docs/openapispecs/rooms-api/rooms-api-specification/rooms-api/updateunit)

### Response body example

The following is a response snippet:

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}
### Response body elements

The following table describes the response elements:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `warnings` | Contains any warnings in the request | object | - |
| `errors` | Contains any errors in the request | object | - |
| `meta` | Contains metadata information about the response | object | - |
| **>** `ruid` | Specifies the unique request ID | string | You can share this ID with Booking.com customer support when you run into an issue This can help in understanding what went wrong |


## Deleting a unit


```http
DELETE
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/units/{unitID}
```

Note that you can delete a unit only if there are no active or future reservations for that unit.
Deleting a unit is irreversible.

### Header parameter

The following table describes the elements you can add in the header:

| Header | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | optional | Currently supports the value:  1.0 |


### Path parameters

The following table describes the elements you must specify in the path:

| Element | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `propertyId` | Specifies the unique ID of the property | integer | required | Must be valid and connected to your account |
| `unitID` | Specifies the unique ID of the unit to deactivate | integer | required | Must belong to the property |


### Response body example

The following is a response snippet:

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}
### Response body elements

The following table describes the response elements:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `warnings` | Contains any warnings in the request | object | - |
| `errors` | Contains any errors in the request | object | - |
| `meta` | Contains metadata information about the response | object | - |
| **>** `ruid` | Specifies the unique request ID | string | You can share this ID with Booking.com customer support when you run into an issue This can help in understanding what went wrong |


## Retrieving units


```http
GET
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/units?debug_info=false
```

Retrieve all units available in the specified property.
When updating a unit, you can also copy the relevant portion of the response from this endpoint and use it as the request body.

### Header parameter

The following table describes the elements you can add in the header:

| Header | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | optional | Currently supports the value:  1.0 |


### Path parameters

The following table describes the elements you must specify in the path:

| Element | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `propertyId` | Specifies the unique ID of the property | integer | required | Must be valid and connected to your account |
| `debug_info` | Specifies whether to return `unit_name_fallback` in response | boolean | optional | false |


### Response body example

The following is a response body snippet:

{
  "data": [
    {
      "unit_id": 1178287071,
      "configuration": {
        "unit_type_id": 9,
        "rooms": [
          {
            "type": "GUEST_ROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 3,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              },
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 2
                  }
                ],
                "is_default_configuration": false
              }
            ]
          }
        ]
      },
      "unit_name_id": 255,
      "number_of_units": 20,
      "smoking_policy": "NONSMOKING",
      "size": {
        "value": 24.0,
        "unit": "SQM"
      },
      "partner_reference_name": "Test double with multiple bed configurations",
      "floor_numbers_located_on": [
        1,
        2,
        3,
        4,
        5
      ],
      "occupancy_details": {
        "max_guests": 2,
        "max_adults": 2,
        "max_children": 1,
        "max_infants": 1,
        "max_infants_on_top": 0
      },
      "max_children_that_pay_children_rate": 1,
      "extra_beds_configuration": {
        "extra_beds": 0,
        "cribs": 1,
        "is_crib_and_extra_bed_allowed": false
      }
    },
    {
      "unit_id": 1178287072,
      "configuration": {
        "unit_type_id": 1,
        "rooms": [
          {
            "type": "BEDROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 1
                  },
                  {
                    "bed_type_id": 6,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              }
            ]
          },
          {
            "type": "BEDROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 3
                  }
                ],
                "is_default_configuration": true
              }
            ]
          },
          {
            "type": "LIVING_ROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 5,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              }
            ]
          }
        ]
      },
      "unit_name_id": 1463,
      "number_of_units": 5,
      "smoking_policy": "SMOKING_AND_NONSMOKING",
      "size": {
        "value": 155.0,
        "unit": "SQM"
      },
      "partner_reference_name": "Test two-bedroom apartment",
      "floor_numbers_located_on": [
        2
      ],
      "occupancy_details": {
        "max_guests": 5,
        "max_adults": 5,
        "max_children": 4,
        "max_infants": 4,
        "max_infants_on_top": 0
      },
      "max_children_that_pay_children_rate": 2,
      "extra_beds_configuration": {
        "extra_beds": 1,
        "cribs": 0,
        "is_crib_and_extra_bed_allowed": false
      }
    }
  ],
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}
### Response body elements

The following table describes the response elements:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `data` | Contains details of the unit created. | object | - |
| **>** `unit_id` | Specifies the unit ID | string | - |
| **>** `configuration` | Contains the unit configuration | object | - |
| **>>** `unit_type_id` | Specifies the unit type ID | enumerated string | - |
| **>>** `rooms` | Contains the room details provided the unit type supports rooms (also known as subrooms) | array of objects | - |
| **>>>** `type` | Specifies the room type supported by the unit type | enumerated string | - |
| **>>>** `bed_configurations` | Contains the details of the bed available in the room | object | - |
| **>>>>** `beds` | Contains the bed type and the total number of beds | array of objects | - |
| **>>>>>** `bed_type_id` | Specifies the bed type ID that is supported by the unit type | enumerated integer | - |
| **>>>>>** `bed_count` | Specifies the total number of beds available in the unit/room | integer | - |
| **>>>>** `is_default_configuration` | Specifies whether the specified bed configuration is default for the unit/room | boolean | - |
| **>** `unit_name_id` | Specifies the unit name ID that is part of the unit type | string | - |
| **>** `number_of_units` | Specifies the total number of rooms available at the property for the specified room type | integer | - |
| **>** `smoking_policy` | Specifies the smoking policy in the room | enumerated string | - |
| **>>** `size` | Contains the unit size details | object | - |
| **>>>** `value` | Specifies the unit size in the chosen unit | integer | - |
| **>>>** `unit` | Specifies the unit of measurement to represent the unit size | enumerated string | - |
| **>** `partner_reference_name` | Specifies a custom unit name that is visible in the extranet and in the API response | string | - |
| **>** `floor_numbers_located_on` | Specifies the floor where the unit is located | array of integer(s) | - |
| **>** `occupancy_details`1 | Contains the occupancy details of the unit | object | - |
| **>>** `max_guests` | Specifies the maximum guest occupancy for the unit | integer | - |
| **>>** `max_adults` | Specifies the maximum adult occupancy for the unit | integer | - |
| **>>** `max_children` | Specifies the maximum occupancy of children (ages 3-17) per unit. | integer | - |
| **>>** `max_infants` | Specifies the maximum infants (0-2) occupancy for the unit count toward `max_guests` | integer | - |
| **>>** `max_infants_on_top` | Specifies the maximum infants (0-2) occupancy for the unit on top of `max_guests` | integer | - |
| `max_children_that_pay_children_rate` | Specifies the maximum number of children eligible for the child rate | integer | - |
| **>** `extra_beds_configuration` | Contains the extra beds details for the unit | object | - |
| **>>** `extra_beds` | Specifies the total number of extra beds available on request per room/unit | integer | - |
| **>>** `cribs` | Specifies the total number of extra cribs available on request per room/unit | integer | - |
| **>>** `is_crib_and_extra_bed_allowed` | Specifies whether guests have the option of requesting both the extra bet and crib in the room/unit | boolean | - |
| **>** `unit_name_fallback` | Contains a unit name; it can be used to read custom unit names not present in [meta](/connectivity/docs/rooms-api/rooms-api-meta-information#path-parameters) | string | - |
| `warnings` | Contains any warnings in the request | object | - |
| `errors` | Contains any errors in the request | object | - |
| `meta` | Contains metadata information about the response | object | - |
| **>** `ruid` | Specifies the unique request ID | string | You can share this ID with Booking.com customer support when you run into an issue This can help in understanding what went wrong |


1 - if the provider feature: `rooms_api_old_occupancy_enabled` is enabled, you see `occupancy` containing only `max_guests`, `max_adults` and `max_children`. For more details, see the [Migration guide](#migration-guide-for-connectivity-providers-that-implemented-rooms-api-before-5-june-2025).

## Retrieving deleted units


```http
GET
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/deleted-units?debug_info=false
```

Retrieve previously deleted units for the specified property.
Note that the deleted units are read-only and cannot be restored.

### Header parameter

The following table describes the elements you can add in the header:

| Header | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | optional | Currently supports the value:  1.0 |


### Path parameters

The following table describes the elements you must specify in the path:

| Element | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `propertyId` | Specifies the unique ID of the property | integer | required | Must be valid and connected to your account |
| `debug_info` | Specifies whether to return `unit_name_fallback` in response | boolean | optional | false |


### Response body example

The following is a response body snippet:

{
  "data": [
    {
      "unit_id": 1178287071,
      "configuration": {
        "unit_type_id": 9,
        "rooms": [
          {
            "type": "GUEST_ROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 3,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              },
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 2
                  }
                ],
                "is_default_configuration": false
              }
            ]
          }
        ]
      },
      "unit_name_id": 255,
      "number_of_units": 20,
      "smoking_policy": "NONSMOKING",
      "size": {
        "value": 24.0,
        "unit": "SQM"
      },
      "partner_reference_name": "Test double with multiple bed configurations",
      "floor_numbers_located_on": [
        1,
        2,
        3,
        4,
        5
      ],
      "occupancy_details": {
        "max_guests": 2,
        "max_adults": 2,
        "max_children": 1,
        "max_infants": 1,
        "max_infants_on_top": 0
      },
      "max_children_that_pay_children_rate": 1,
      "extra_beds_configuration": {
        "extra_beds": 0,
        "cribs": 1,
        "is_crib_and_extra_bed_allowed": false
      }
    },
    {
      "unit_id": 1178287072,
      "configuration": {
        "unit_type_id": 1,
        "rooms": [
          {
            "type": "BEDROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 1
                  },
                  {
                    "bed_type_id": 6,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              }
            ]
          },
          {
            "type": "BEDROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 3
                  }
                ],
                "is_default_configuration": true
              }
            ]
          },
          {
            "type": "LIVING_ROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 5,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              }
            ]
          }
        ]
      },
      "unit_name_id": 1463,
      "number_of_units": 5,
      "smoking_policy": "SMOKING_AND_NONSMOKING",
      "size": {
        "value": 155.0,
        "unit": "SQM"
      },
      "partner_reference_name": "Test two-bedroom apartment",
      "floor_numbers_located_on": [
        2
      ],
      "occupancy_details": {
        "max_guests": 5,
        "max_adults": 5,
        "max_children": 4,
        "max_infants": 4,
        "max_infants_on_top": 0
      },
      "max_children_that_pay_children_rate": 2,
      "extra_beds_configuration": {
        "extra_beds": 1,
        "cribs": 0,
        "is_crib_and_extra_bed_allowed": false
      }
    }
  ],
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}
### Response body elements

The following table describes the response elements:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `data` | Contains details of the unit created. | object | - |
| **>** `unit_id` | Specifies the unit ID | string | - |
| **>** `configuration` | Contains the unit configuration | object | - |
| **>>** `unit_type_id` | Specifies the unit type ID | enumerated string | - |
| **>>** `rooms` | Contains the room details provided the unit type supports rooms (also known as subrooms) | array of objects | - |
| **>>>** `type` | Specifies the room type supported by the unit type | enumerated string | - |
| **>>>** `bed_configurations` | Contains the details of the bed available in the room | object | - |
| **>>>>** `beds` | Contains the bed type and the total number of beds | array of objects | - |
| **>>>>>** `bed_type_id` | Specifies the bed type ID that is supported by the unit type | enumerated integer | - |
| **>>>>>** `bed_count` | Specifies the total number of beds available in the unit/room | integer | - |
| **>>>>** `is_default_configuration` | Specifies whether the specified bed configuration is default for the unit/room | boolean | - |
| **>** `unit_name_id` | Specifies the unit name ID that is part of the unit type | string | - |
| **>** `number_of_units` | Specifies the total number of rooms available at the property for the specified room type | integer | - |
| **>** `smoking_policy` | Specifies the smoking policy in the room | enumerated string | - |
| **>>** `size` | Contains the unit size details | object | - |
| **>>>** `value` | Specifies the unit size in the chosen unit | integer | - |
| **>>>** `unit` | Specifies the unit of measurement to represent the unit size | enumerated string | - |
| **>** `partner_reference_name` | Specifies a custom unit name that is visible in the extranet and in the API response | string | - |
| **>** `floor_numbers_located_on` | Specifies the floor where the unit is located | array of integer(s) | - |
| **>** `occupancy_details`1 | Contains the occupancy details of the unit | object | - |
| **>>** `max_guests` | Specifies the maximum guest occupancy for the unit | integer | - |
| **>>** `max_adults` | Specifies the maximum adult occupancy for the unit | integer | - |
| **>>** `max_children` | Specifies the maximum occupancy of children (ages 3-17) per unit. | integer | - |
| **>>** `max_infants` | Specifies the maximum infants (0-2) occupancy for the unit count toward `max_guests` | integer | - |
| **>>** `max_infants_on_top` | Specifies the maximum infants (0-2) occupancy for the unit on top of `max_guests` | integer | - |
| `max_children_that_pay_children_rate` | Specifies the maximum number of children eligible for the child rate | integer | - |
| **>** `extra_beds_configuration` | Contains the extra beds details for the unit | object | - |
| **>>** `extra_beds` | Specifies the total number of extra beds available on request per room/unit | integer | - |
| **>>** `cribs` | Specifies the total number of extra cribs available on request per room/unit | integer | - |
| **>>** `is_crib_and_extra_bed_allowed` | Specifies whether guests have the option of requesting both the extra bet and crib in the room/unit | boolean | - |
| **>** `unit_name_fallback` | Contains a unit name. Specify to read custom unit names not present in [meta endpoint.](/connectivity/docs/rooms-api/rooms-api-meta-information#path-parameters) | string | - |
| `warnings` | Contains any warnings in the request | object | - |
| `errors` | Contains any errors in the request | object | - |
| `meta` | Contains metadata information about the response | object | - |
| **>** `ruid` | Specifies the unique request ID | string | You can share this ID with Booking.com customer support when you run into an issue This can help in understanding what went wrong |


1 - if the provider feature: `rooms_api_old_occupancy_enabled` is enabled, you see `occupancy` containing only `max_guests`, `max_adults` and `max_children`. For more details, see the [Migration guide](#migration-guide-for-connectivity-providers-that-implemented-rooms-api-before-5-june-2025).