openapi: 3.2.0
info:
  title: Rooms API
  description: Contains Rooms API specification
  contact:
    name: Connectivity Team
    url: https://connect.booking.com
    email: connectivity@booking.com
  version: '1.3'
servers:
- url: https://supply-xml.booking.com/
  description: Test using live endpoint
tags:
- name: rooms-api
  description: Create, update, retrieve and delete property units
paths:
  /rooms-api/properties/{property-id}/units:
    get:
      tags:
      - rooms-api
      summary: Get units
      description: Get all active units for a property
      operationId: getUnits
      parameters:
      - name: property-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: debug_info
        in: query
        description: Enable debug to return <code>$.unit_name_fallback</code> field in response
        required: false
        schema:
          type: string
          default: 'false'
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseListUnit'
    post:
      tags:
      - rooms-api
      summary: Create unit
      description: Create new unit for a property
      operationId: createUnit
      parameters:
      - name: property-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnitCreate'
            examples:
              MULTI_ROOM_UNIT_W_MANY_ROOMS:
                description: Create a Villa with 2 bedrooms and a living room with sofa
                value:
                  configuration:
                    unit_type_id: 31
                    rooms:
                    - type: BEDROOM_SUBROOM
                      bed_configurations:
                      - beds:
                        - bed_type_id: 6
                          bed_count: 1
                        - bed_type_id: 1
                          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
                    - type: LIVING_ROOM_SUBROOM
                  unit_name_id: 4180
                  number_of_units: 5
                  smoking_policy: SMOKING_AND_NONSMOKING
                  size:
                    value: 155
                    unit: SQM
                  partner_reference_name: Example two-bedroom villa
                  floor_numbers_located_on:
                  - 2
                  occupancy_details:
                    max_guests: 5
                    max_adults: 5
                    max_children: 4
                    max_infants: 4
                    max_infants_on_top: 0
                  extra_beds_configuration:
                    extra_beds: 1
                    cribs: 0
                    is_crib_and_extra_bed_allowed: false
              MULTI_ROOM_UNIT_W_BEDROOM_ONLY:
                description: Create a one-bedroom Apartment with a living room
                value:
                  configuration:
                    unit_type_id: 1
                    rooms:
                    - type: BEDROOM_SUBROOM
                      bed_configurations:
                      - beds:
                        - bed_type_id: 3
                          bed_count: 1
                        is_default_configuration: true
                    - type: LIVING_ROOM_SUBROOM
                  unit_name_id: 865
                  number_of_units: 5
                  smoking_policy: SMOKING
                  size:
                    value: 155
                    unit: SQM
                  partner_reference_name: Example single-bedroom apartment
                  floor_numbers_located_on:
                  - 2
                  occupancy_details:
                    max_guests: 3
                    max_adults: 3
                    max_children: 2
                    max_infants: 0
                    max_infants_on_top: 2
                  extra_beds_configuration:
                    extra_beds: 1
                    cribs: 1
                    is_crib_and_extra_bed_allowed: true
              MULTI_ROOM_UNIT_W_MINIMAL_REQUIRED_FIELDS:
                description: Create a one-bedroom Suite with minimum required fields
                value:
                  configuration:
                    unit_type_id: 5
                    rooms:
                    - type: BEDROOM_SUBROOM
                      bed_configurations:
                      - beds:
                        - bed_type_id: 3
                          bed_count: 1
                        is_default_configuration: true
                  unit_name_id: 746
              SINGLE_ROOM_UNIT_W_MULTIPLE_BED_CONFIGS:
                description: Create a Double with multiple bed configurations
                value:
                  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
                    unit: SQM
                  partner_reference_name: Example 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
                  extra_beds_configuration:
                    extra_beds: 0
                    cribs: 1
                    is_crib_and_extra_bed_allowed: false
              SINGLE_ROOM_UNIT_W_SINGLE_BED_CONFIG:
                description: Create a Studio with a single bed configuration
                value:
                  configuration:
                    unit_type_id: 12
                    rooms:
                    - type: GUEST_ROOM
                      bed_configurations:
                      - beds:
                        - bed_type_id: 3
                          bed_count: 1
                        is_default_configuration: true
                  unit_name_id: 1147
                  number_of_units: 20
                  smoking_policy: NONSMOKING
                  size:
                    value: 24
                    unit: SQM
                  partner_reference_name: Example studio with a single bed configuration
                  occupancy_details:
                    max_guests: 2
                    max_adults: 2
                    max_children: 1
                    max_infants: 1
                    max_infants_on_top: 0
                  extra_beds_configuration:
                    extra_beds: 0
                    cribs: 1
                    is_crib_and_extra_bed_allowed: false
              SINGLE_ROOM_UNIT_W_MINIMUM_REQUIRED_FIELDS:
                description: Create a Single with minimum required fields
                value:
                  configuration:
                    unit_type_id: 10
                    rooms:
                    - type: GUEST_ROOM
                      bed_configurations:
                      - beds:
                        - bed_type_id: 1
                          bed_count: 1
                        is_default_configuration: true
                  unit_name_id: 69
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseUnit'
  /rooms-api/properties/{property-id}/units/{unit-id}:
    delete:
      tags:
      - rooms-api
      summary: Delete unit
      description: Delete existing unit for a property
      operationId: deleteUnit
      parameters:
      - name: property-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: unit-id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseObject'
    patch:
      tags:
      - rooms-api
      summary: Update unit
      description: Update existing unit for a property
      operationId: updateUnit
      parameters:
      - name: property-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: unit-id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Unit'
            examples:
              MULTI_ROOM_ADD_BED:
                description: Add additional single bed to bedroom for multi-room unit
                value:
                  configuration:
                    unit_type_id: 1
                    rooms:
                    - type: BEDROOM_SUBROOM
                      bed_configurations:
                      - beds:
                        - bed_type_id: 3
                          bed_count: 1
                        - bed_type_id: 1
                          bed_count: 1
                        is_default_configuration: true
                    - type: LIVING_ROOM_SUBROOM
                      bed_configurations:
                      - beds:
                        - bed_type_id: 5
                          bed_count: 1
                        is_default_configuration: true
              MULTI_ROOM_REMOVE_BED:
                description: Remove beds from a living room for multi-room unit
                value:
                  configuration:
                    unit_type_id: 1
                    rooms:
                    - type: BEDROOM_SUBROOM
                      bed_configurations:
                      - beds:
                        - bed_type_id: 3
                          bed_count: 1
                        - bed_type_id: 1
                          bed_count: 1
                        is_default_configuration: true
                    - type: LIVING_ROOM_SUBROOM
              SINGLE_ROOM_BED_CONFIG:
                description: Add additional bed configuration for mono-room unit
                value:
                  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
              OBJECT_TYPE_FIELDS:
                description: Update size, occupancy and extra beds configuration for any unit type
                value:
                  size:
                    value: 99
                    unit: SQM
                  occupancy_details:
                    max_guests: 5
                    max_adults: 5
                    max_children: 4
                    max_infants: 4
                    max_infants_on_top: 0
                  extra_beds_configuration:
                    extra_beds: 2
                    cribs: 1
                    is_crib_and_extra_bed_allowed: true
              SIMPLE_FIELDS:
                description: Update unit name, number of units, smoking policy and partner reference name for any unit type
                value:
                  unit_name_id: 2273
                  number_of_units: 3
                  smoking_policy: SMOKING
                  partner_reference_name: Example reference name
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseObject'
  /rooms-api/properties/{property-id}/deleted-units:
    get:
      tags:
      - rooms-api
      summary: Get deleted units (read only)
      description: Get all deleted units for a property (read only)
      operationId: getDeletedUnits
      parameters:
      - name: property-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: debug_info
        in: query
        description: Enable debug to return <code>$.unit_name_fallback</code> field in response
        required: false
        schema:
          type: string
          default: 'false'
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseListUnit'
components:
  schemas:
    ApiResponseUnit:
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          $ref: '#/components/schemas/Unit'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ApiError:
      properties:
        message:
          type: string
        code:
          type: integer
          format: int32
          description: ''
        details:
          type: object
          properties:
            fields:
              type: array
              description: ''
              items:
                type: string
        description:
          type: string
    ExtraBedsConfiguration:
      description: Extra bed & crib options
      properties:
        extra_beds:
          type: integer
          format: int32
          description: Number of extra beds you can provide
          maximum: 100
          minimum: 0
        cribs:
          type: integer
          format: int32
          description: Number of cribs you can provide
          maximum: 100
          minimum: 0
        is_crib_and_extra_bed_allowed:
          type: boolean
          description: Both extra beds and cribs can be provided (<code>true</code>) or only one of the options (<code>false</code>)?
      required:
      - cribs
      - extra_beds
      - is_crib_and_extra_bed_allowed
    ApiResponseObject:
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          type: 'null'
          description: ''
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    Room:
      properties:
        type:
          type: string
          description: '<ul>

            <li>For multi-room units you must add one or more <code>BEDROOM_SUBROOM</code> or <code>LIVING_ROOM_SUBROOM</code>, at least one of the rooms must have beds</li>

            <li>For single-room units you must add exactly one <code>GUEST_ROOM</code></li>

            </ul>

            '
          enum:
          - BEDROOM_SUBROOM
          - LIVING_ROOM_SUBROOM
          - GUEST_ROOM
        bed_configurations:
          type: array
          items:
            $ref: '#/components/schemas/BedConfiguration'
      required:
      - type
    Size:
      properties:
        value:
          type: number
          format: double
          description: Must be a value between 1 and 9999.99
        unit:
          type: string
          description: SQM (square meters) or SQFT (square feet)
          enum:
          - SQM
          - SQFT
      required:
      - unit
      - value
    ExtraBedsConfigurationCreate:
      description: Extra bed & crib options
      properties:
        extra_beds:
          type: integer
          format: int32
          default: 0
          description: Number of extra beds you can provide
          maximum: 100
          minimum: 0
        cribs:
          type: integer
          format: int32
          default: 0
          description: Number of cribs you can provide
          maximum: 100
          minimum: 0
        is_crib_and_extra_bed_allowed:
          type: boolean
          default: false
          description: Both extra beds and cribs can be provided (<code>true</code>) or only one of the options (<code>false</code>)?
    BedConfiguration:
      description: '<ul>

        <li>For multi-room unit you must add exactly one bed configuration</li>

        <li>For single-room unit you must add at least one bed configuration, others are optional</li>

        <li>Bed type ID provided must exist and be active in meta (see <code>$.bed_types[*].is_active</code>)</li>

        <li>Same bed type ID must be repeated within a single bed configuration</li>

        </ul>

        '
      properties:
        beds:
          type: array
          items:
            $ref: '#/components/schemas/Bed'
          minItems: 1
        is_default_configuration:
          type: boolean
          description: Exactly one default bed configuration is mandatory for each room provided
      required:
      - beds
      - is_default_configuration
    OccupancyCreate:
      deprecated: true
      properties:
        max_guests:
          type: integer
          format: int32
          default: 1
          description: Maximum number of guests
          maximum: 50
          minimum: 1
        max_adults:
          type: integer
          format: int32
          default: 1
          description: Maximum number of adults
          maximum: 50
          minimum: 1
        max_children:
          type: integer
          format: int32
          default: 0
          description: Maximum number of children (0-17 years old)
          maximum: 49
          minimum: 0
    Configuration:
      properties:
        unit_type_id:
          type: integer
          format: int32
          description: '<ul>

            <li>Must exist and be active in meta (see <code>$.unit_type[*].id</code> and <code>$.unit_type[*].is_active</code>) for unit creation/update</li>

            <li>Must be valid for property''s category in meta (see <code>$.unit_type[*].valid_property_categories</code>)</li>

            </ul>

            '
        rooms:
          type: array
          items:
            $ref: '#/components/schemas/Room'
          minItems: 1
      required:
      - rooms
      - unit_type_id
    ApiResponseListUnit:
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Unit'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ResponseMeta:
      properties:
        ruid:
          type: string
    OccupancyDetails:
      properties:
        max_guests:
          type: integer
          format: int32
          description: Maximum number of guests
          maximum: 50
          minimum: 1
        max_adults:
          type: integer
          format: int32
          description: Maximum number of adults
          maximum: 50
          minimum: 1
        max_children:
          type: integer
          format: int32
          description: Maximum number of children excluding infants (3-17 years old)
          maximum: 49
          minimum: 0
        max_infants:
          type: integer
          format: int32
          description: Maximum number of infants (0-2 years old)
          maximum: 49
          minimum: 0
        max_infants_on_top:
          type: integer
          format: int32
          description: Maximum number of infants (0-2 years old) on top of maximum number of guests
          maximum: 49
          minimum: 0
      required:
      - max_adults
      - max_children
      - max_guests
      - max_infants
      - max_infants_on_top
    Bed:
      properties:
        bed_type_id:
          type: integer
          format: int32
        bed_count:
          type: integer
          format: int32
      required:
      - bed_count
      - bed_type_id
    Unit:
      description: Unit schema; use meta endpoint for fetching relevant meta data
      properties:
        unit_id:
          type: integer
          format: int64
        configuration:
          $ref: '#/components/schemas/Configuration'
        unit_name_id:
          type: integer
          format: int32
          description: '<ul>

            <li>The list of available unit names can be found in meta (see <code>$.unit_names</code>)</li>

            <li>Set <code>debug_info</code> as <code>true</code> to retrieve the generated unit name (see <code>$.unit_name_fallback</code>)</li>

            </ul>

            '
        number_of_units:
          type: integer
          format: int32
          description: Number of units must be between 0 and 32000
        smoking_policy:
          type: string
          description: Room smoking policy
          enum:
          - SMOKING
          - NONSMOKING
          - SMOKING_AND_NONSMOKING
        size:
          $ref: '#/components/schemas/Size'
        partner_reference_name:
          type: string
          description: Internal room name, visible only in API and Extranet
        floor_numbers_located_on:
          type: array
          description: One or more floors where the unit is located; 0 is a ground floor
          items:
            type: integer
            format: int32
            description: One or more floors where the unit is located; 0 is a ground floor
        occupancy:
          $ref: '#/components/schemas/Occupancy'
        occupancy_details:
          $ref: '#/components/schemas/OccupancyDetails'
        extra_beds_configuration:
          $ref: '#/components/schemas/ExtraBedsConfiguration'
        unit_name_fallback:
          type: string
          description: Contains unit name (<code>EN_GB</code> locale) for any unit name ID, including those missing in meta (for debug purposes only; read only)
    UnitCreate:
      description: Unit creation schema; use meta endpoint for fetching relevant meta data
      properties:
        configuration:
          $ref: '#/components/schemas/Configuration'
        unit_name_id:
          type: integer
          format: int32
          description: '<ul>

            <li>The list of available unit names can be found in meta (see <code>$.unit_names</code>)</li>

            <li>Set <code>debug_info</code> as <code>true</code> to retrieve the generated unit name (see <code>$.unit_name_fallback</code>)</li>

            </ul>

            '
        number_of_units:
          type: integer
          format: int32
          default: 1
          description: Number of units must be between 0 and 32000
        smoking_policy:
          type: string
          default: SMOKING_AND_NONSMOKING
          enum:
          - SMOKING
          - NONSMOKING
          - SMOKING_AND_NONSMOKING
        size:
          $ref: '#/components/schemas/Size'
        partner_reference_name:
          type: string
          description: Internal room name, visible only in API and Extranet
        floor_numbers_located_on:
          type: array
          description: One or more floors where the unit is located; 0 is a ground floor
          items:
            type: integer
            format: int32
            description: One or more floors where the unit is located; 0 is a ground floor
        occupancy:
          $ref: '#/components/schemas/OccupancyCreate'
        occupancy_details:
          $ref: '#/components/schemas/OccupancyDetailsCreate'
        extra_beds_configuration:
          $ref: '#/components/schemas/ExtraBedsConfigurationCreate'
      required:
      - configuration
    OccupancyDetailsCreate:
      properties:
        max_guests:
          type: integer
          format: int32
          default: 1
          description: Maximum number of guests
          maximum: 50
          minimum: 1
        max_adults:
          type: integer
          format: int32
          default: 1
          description: Maximum number of adults
          maximum: 50
          minimum: 1
        max_children:
          type: integer
          format: int32
          default: 0
          description: Maximum number of children excluding infants (3-17 years old)
          maximum: 49
          minimum: 0
        max_infants:
          type: integer
          format: int32
          default: 0
          description: Maximum number of infants (0-2 years old)
          maximum: 49
          minimum: 0
        max_infants_on_top:
          type: integer
          format: int32
          default: 0
          description: Maximum number of infants (0-2 years old) on top of maximum number of guests
          maximum: 49
          minimum: 0
    Occupancy:
      deprecated: true
      properties:
        max_guests:
          type: integer
          format: int32
          description: Maximum number of guests
          maximum: 50
          minimum: 1
        max_adults:
          type: integer
          format: int32
          description: Maximum number of adults
          maximum: 50
          minimum: 1
        max_children:
          type: integer
          format: int32
          description: Maximum number of children (0-17 years old)
          maximum: 49
          minimum: 0
      required:
      - max_adults
      - max_children
      - max_guests
x-tagGroups:
- name: API Endpoints
  tags:
  - rooms-api
  - rooms-api-bulk
  - meta
- name: Documentation
  tags:
  - About Try it