Managing units

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

You can:

Create units (why units instead of rooms?)
Update units
Deactivate unit
Retrieve unit details

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, you can create a unit of type Apartment (unit type ID 1) named Apartment with Sea View (unit name ID 44) with a Large bed (bed type ID 6) inside.

These IDs and their attributes constitute the Rooms API metadata, which can be retrieved using the Rooms API meta endpoint. See the meta endpoint's documentation and Open API specification.

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 multi-room or mono-room.

Understand the difference between multi-room and mono-room units

There are two categories of units supported by the Rooms API: mono-room and multi-room. It is important to understand the difference, because each category has it own requirements to pass validations.

Category	Example unit types	Multiple rooms supported	Type of rooms supported	Multiple bed configurations supported
Multi-room unit	`Apartment`, `Villa`, `Suite`	yes	`BEDROOM_SUBROOM`, `LIVING_ROOM_SUBROOM`	no
Mono-room unit	`Studio`, `Double`	no	`GUEST_ROOM`	yes

Learn more about the create and update requests validations

The request body for POST and PATCH requests is validated against a set of rules. These include generic rules applicable to all units, as well as specific rules based on unit category (mono- or multi-room) and unit type.

Create a unit

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	required¹	n/a	`Room > SizeMeasurement`
> `unit`	Specifies the unit of measurement to represent the unit size	enumerated string	required¹	n/a	`Room > SizeMeasurementUnit`
`partner_reference_name`	Specifies a custom unit name visible in the extranet and API response	string	optional	`null`	New field
`room_located_on_floors`	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	conditional²	n/a	`SubRoom > Amenities`
>>> `beds`	Contains the bed type and the total number of beds	array of objects	required¹	n/a
>>>> `bed_type_id`	Specifies the bed type ID supported by the unit type	enumerated integer	required¹	n/a	`AmenityCode (or RoomAmenityCode)`
>>>> `bed_count`	Specifies the total number of beds of the type specified above	integer	required¹	n/a	`Quantity (or Value)`
>>> `is_default_configuration`	Specifies whether the specified bed configuration is default for the unit/room	boolean	required¹	n/a	`Configuration`
`occupancy`	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 child occupancy for the unit	integer	optional	`0`	`Occupancy > MaxChildOccupancy`
`max_children_that_pay_children_rate`	Specifies the maximum number of children eligible for the child rate	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

¹ - required only if a parent field is provided
² - required for room types GUEST_ROOM and BEDROOM_SUBROOM, optional for LIVING_ROOM_SUBROOM

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": {
    "max_guests": 5,
    "max_adults": 5,
    "max_children": 4
  },
  "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.

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": {
      "max_guests": 5,
      "max_adults": 5,
      "max_children": 4
    },
    "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`	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 child occupancy for the unit.	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.

Updating a unit

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 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	required¹	`Room > SizeMeasurement`
> `unit`	Specifies the unit of measurement to represent the unit size	enumerated string	required¹	`Room > SizeMeasurementUnit`
`partner_reference_name`	Specifies a custom unit name visible in the extranet and API response	string	optional	New field
`room_located_on_floors`	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	required¹	`Room > RoomType`
> `rooms`	Contains the room details provided the unit type supports rooms	array of objects	required¹
>> `type`	Specifies the room type supported by the unit type	enumerated string	required¹	`SubRoom > RoomType`
>> `bed_configurations`	Contains the details of the bed available in the room	object	conditional²	`SubRoom > Amenities`
>>> `beds`	Contains the bed type and the total number of beds	array of objects	required¹
>>>> `bed_type_id`	Specifies the bed type ID supported by the unit type	enumerated integer	required¹	`AmenityCode (or RoomAmenityCode)`
>>>> `bed_count`	Specifies the total number of beds of the type specified above	integer	required¹	`Quantity (or Value)`
>>> `is_default_configuration`	Specifies whether the specified bed configuration is default for the unit/room	boolean	required¹	`Configuration`
`occupancy`	Contains the occupancy details of the unit	object	optional	-
> `max_guests`	Specifies the maximum guest occupancy for the unit	integer	required¹	`Occupancy > MaxOccupancy`
> `max_adults`	Specifies the maximum adult occupancy for the unit	integer	required¹	`Occupancy > MaxAdultOccupancy`
> `max_children`	Specifies the maximum child occupancy for the unit	integer	required¹	`Occupancy > MaxChildOccupancy`
`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	required¹	`Quantities > MaxRollaways`
> `cribs`	Specifies the total number of extra cribs available on request per unit/room	integer	required¹	`Quantities > MaxCribs`
> `is_crib_and_extra_bed_allowed`	Specifies whether guests can request both the extra bed and crib in the unit/room	boolean	required¹	New field

¹ - required only if a parent field is provided
² - required for room types GUEST_ROOM and BEDROOM_SUBROOM, optional for LIVING_ROOM_SUBROOM

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": {
      "max_guests": 4,
      "max_adults": 4,
      "max_children": 3
  }
}

For more request examples for various use cases, see the examples in the API Explorer section in the Open API specification.

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

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 unit details

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": {
        "max_guests": 2,
        "max_adults": 2,
        "max_children": 1
      },
      "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": {
        "max_guests": 5,
        "max_adults": 5,
        "max_children": 4
      },
      "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`	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 child occupancy for the unit.	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	string	Custom unit names cannot be used in create and update requests
`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.