Introduction to Rooms API
Rooms API allows you to manage rooms, configure bed arrangements, and set occupancy limits among other tasks. Implementing Rooms API also requires implementing Facilities API to manage bathrooms and other room facilities.
Adding rooms to a property is an important step towards setting up availability. To complete the availability setup, you also need to define rate plans and room rates.
Understanding Rooms API terminology
At Booking.com, we refer to sellable inventory items as rooms. However, during the development of Rooms API, we recognized that this term doesn't accurately represent all the resources this API manages.
Renaming Rooms to Units
While room appropriately describes a standard hotel accommodation (like a Double room), it becomes inadequate when referring to:
- hotel suites: Larger accommodations with multiple rooms
- vacation rentals: Properties such as apartments, villas, or cottages
- multi-room accommodations: Any inventory item containing multiple distinct rooms
To address this limitation, we've adopted the term unit within the Rooms API. A unit can contain one or more rooms, providing a more flexible and accurate way to describe our diverse inventory.
The term unit is specific to the Rooms API only. Other Booking.com solutions, interfaces and documentation will continue to use the term rooms, such as in room rates or room facilities.
Unit types and metadata
Rooms API offers a variety of unit types, allowing you to configure accommodation options based on the property's requirements. Each unit type supports specific characteristics and behaviours that you can configure. The Rooms API meta endpoint provides you with the essential information you need to configure your units effectively.
Introducing the Rooms API meta endpoint
To help you work with these unit types, we provide a meta endpoint that offers:
- complete list of supported unit types (e.g., Double, Studio, Apartment, Villa)
- list of unit names and bed types for each unit type
- classification of unit types by room capacity:
- single-room units (e.g., Double, Studio)
- multi-room units (e.g., Apartment, Villa)
- compatibility information showing which unit types are permitted for your specific property category
Consulting this metadata before creating or updating a unit ensures that you configure accommodations that are both valid and appropriate for your property.
Introducing the Rooms API endpoints for managing units
Use the Rooms API endpoints to:
The OpenAPI specification provides details on all actions supported by the Rooms API, along with request examples for various scenarios. You can access these examples using the Try it feature.
Considerations before creating units
When creating a unit, make sure to include the following minimum required details:
- unit type ID
- unit name ID
- room and bed configuration
It is important to understand the difference between a single-room unit and a multi-room unit before creating one. Also note that create and update requests are subject to validations specific to the unit type.
Known incompatibilities with Extranet
When accessing the details of the units ("rooms") that were created using the Rooms API in Extranet, you may encounter the following issues:
- warnings that are not returned by the Rooms API. For example, a warning message about a mismatch between the occupancy and the number of beds.
- some data missing in the UI. For example, if you add more than 3 beds to a single-bed configuration only 3 are shown.
These incompatibilities arise because Extranet is designed to provide the best user experience in the UI, and therefore implements stricter rules. This does not mean that a unit (room) created using the API is invalid.
Going live
Before you go live with your API integration, you'll need to meet certain requirements. For more information, see Going Live.