openapi: 3.0.1
info:
  title: Rooms API
  description: Contains Rooms API description
  contact:
    name: Connectivity Team
    url: https://connect.booking.com
    email: connectivity@booking.com
  version: '1.0'
servers:
  - url: https://supply-xml.booking.com/
tags:
  - name: meta
    description: Retrieve listings meta data and translations
  - name: rooms-api
    description: Create, update, retrieve and delete property listings
paths:
  /rooms-api/properties/{propertyId}/listings:
    get:
      tags:
        - rooms-api
      summary: Get listing
      description: Get all active listings for a property
      operationId: getListingsByPropertyId
      parameters:
        - name: propertyId
          in: path
          required: true
          schema:
            type: integer
            format: int32
        - name: debug_info
          in: query
          description: >-
            Enable debug to return <code>$.listing_name_fallback</code> field in
            response
          required: false
          schema:
            type: string
            default: 'false'
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseListListing'
    post:
      tags:
        - rooms-api
      summary: Create listing
      description: Create new listing for a property
      operationId: createListing
      parameters:
        - name: propertyId
          in: path
          required: true
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListingCreate'
            examples:
              Create a Villa with 2 bedrooms and a living room with sofa:
                description: Create a Villa with 2 bedrooms and a living room with sofa
                value:
                  configuration:
                    listing_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
                  listing_name_id: 4180
                  number_of_listings: 5
                  smoking_policy: SMOKING_AND_NONSMOKING
                  size:
                    value: 155
                    unit: SQM
                  partner_reference_name: Example two-bedroom villa
                  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
              Create a one-bedroom Apartment with a living room:
                description: Create a one-bedroom Apartment with a living room
                value:
                  configuration:
                    listing_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
                  listing_name_id: 865
                  number_of_listings: 5
                  smoking_policy: SMOKING
                  size:
                    value: 155
                    unit: SQM
                  partner_reference_name: Example single-bedroom apartment
                  floor_numbers_located_on:
                    - 2
                  occupancy:
                    max_guests: 3
                    max_adults: 3
                    max_children: 1
                    max_children_that_pay_children_rate: 1
                  extra_beds_configuration:
                    extra_beds: 1
                    cribs: 1
                    is_crib_and_extra_bed_allowed: true
              Create a one-bedroom Suite with minimum required fields:
                description: Create a one-bedroom Suite with minimum required fields
                value:
                  configuration:
                    listing_type_id: 5
                    rooms:
                      - type: BEDROOM_SUBROOM
                        bed_configurations:
                          - beds:
                              - bed_type_id: 3
                                bed_count: 1
                            is_default_configuration: true
                  listing_name_id: 746
              Create a Double with multiple bed configurations:
                description: Create a Double with multiple bed configurations
                value:
                  configuration:
                    listing_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
                  listing_name_id: 255
                  number_of_listings: 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:
                    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
              Create a Studio with a single bed configuration:
                description: Create a Studio with a single bed configuration
                value:
                  configuration:
                    listing_type_id: 12
                    rooms:
                      - type: GUEST_ROOM
                        bed_configurations:
                          - beds:
                              - bed_type_id: 3
                                bed_count: 1
                            is_default_configuration: true
                  listing_name_id: 1147
                  number_of_listings: 20
                  smoking_policy: NONSMOKING
                  size:
                    value: 24
                    unit: SQM
                  partner_reference_name: Example studio with a single bed configuration
                  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
              Create a Single with minimum required fields:
                description: Create a Single with minimum required fields
                value:
                  configuration:
                    listing_type_id: 10
                    rooms:
                      - type: GUEST_ROOM
                        bed_configurations:
                          - beds:
                              - bed_type_id: 1
                                bed_count: 1
                            is_default_configuration: true
                  listing_name_id: 69
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseListing'
  /rooms-api/properties/{propertyId}/listings/{listingId}:
    delete:
      tags:
        - rooms-api
      summary: Delete listing
      description: Delete existing listing for a property
      operationId: deleteListing
      parameters:
        - name: propertyId
          in: path
          required: true
          schema:
            type: integer
            format: int32
        - name: listingId
          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 listing
      description: Update existing listing for a property
      operationId: updateListing
      parameters:
        - name: propertyId
          in: path
          required: true
          schema:
            type: integer
            format: int32
        - name: listingId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Listing'
            examples:
              Add additional single bed to bedroom for multi-room listing:
                description: Add additional single bed to bedroom for multi-room listing
                value: |
                  {
                      "configuration": {
                          "listing_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
                                      }
                                  ]
                              },
                          ]
                      }
                  }
              Remove beds from a living room for multi-room listing:
                description: Remove beds from a living room for multi-room listing
                value:
                  configuration:
                    listing_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
              Add additional bed configuration for mono-room listing:
                description: Add additional bed configuration for mono-room listing
                value:
                  configuration:
                    listing_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
              Update size, occupancy and extra beds configuration for any listing type:
                description: >-
                  Update size, occupancy and extra beds configuration for any
                  listing type
                value:
                  size:
                    value: 99
                    unit: SQM
                  occupancy:
                    max_guests: 5
                    max_adults: 5
                    max_children: 2
                    max_children_that_pay_children_rate: 2
                  extra_beds_configuration:
                    extra_beds: 2
                    cribs: 1
                    is_crib_and_extra_bed_allowed: true
              Update listing name, number of listings, smoking policy and partner reference name for any listing type:
                description: >-
                  Update listing name, number of listings, smoking policy and
                  partner reference name for any listing type
                value:
                  listing_name_id: 2273
                  number_of_listings: 3
                  smoking_policy: SMOKING
                  partner_reference_name: Example reference name
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseObject'
  /rooms-api/meta:
    get:
      tags:
        - meta
      summary: Get meta data for listings
      description: >
        Retrieve meta data required for listing creation and update for any
        supported <code>language_code</code>
            <ul>
            <li>Retrieve the list of all listing type IDs allowed for creation/update. For each <code>$.listing_types[*]</code> record you will find:</li>
                <ul>
                <li><code>listing_type_id</code>: the listing type ID you must provide with each create and update request</li>
                <li><code>listing_type_name</code>: string representation of listing type ID (translatable)</li>
                <li><code>is_multi_room</code>: attribute that defines what type of room types you can use add in your listing</li>
                <li><code>is_active</code>: attribute that defines if a listing type is available for creation/update, inactive room types are available for read only</li>
                <li><code>valid_property_categories</code>: list of property categories that allow creation of this listing type</li>
                <li><code>suggested_listing_names</code>: list of listing names that we recommend to use in combination with this listing type</li>
                </ul>
            <li>Retrieve the list of all room name IDs allowed during listing creation/update. For each <code>$.listing_names[*]</code> record you will find:</li>
                <ul>
                <li><code>listing_name_id</code>: the listing name ID you must provide with each create request</li>
                <li><code>listing_name</code>: string representation of listing name ID (translatable)</li>
                </ul>
            <li>Retrieve the list of all bed type IDs allowed during listing creation/update. For each <code>$.bed_types[*]</code> record you will find:</li>
                <ul>
                <li><code>bed_type_id</code>: the bed type ID you must provide when configuring rooms</li>
                <li><code>bed_type_name</code>: string representation of bed type (translatable)</li>
                <li><code>bed_type_description</code>: description of bed type size using metric units (translatable)</li>
                <li><code>bed_type_description_imperial</code>: description of bed type size using imperial units (translatable)</li>
                <li><code>is_active</code>: attribute that defines if a bed type is available for creation/update, inactive bed types are available for read only</li>
                </ul>
            <li>Retrieve the list of all property categories for which you can create a listing. For each property type you will find its name and category ID, as well as an OTA or a Booking.com extended code</li>
            </ul>
      operationId: getRoomMeta
      parameters:
        - name: language_code
          in: query
          description: Language code for localization
          required: false
          schema:
            type: string
            enum:
              - EN_GB
              - EN_US
              - DE
              - NL
              - FR
              - ES
              - ES_AR
              - ES_MX
              - CA
              - IT
              - PT_PT
              - PT_BR
              - 'NO'
              - FI
              - SV
              - DA
              - CS
              - HU
              - RO
              - JA
              - ZH_CN
              - ZH_TW
              - PL
              - EL
              - RU
              - TR
              - BG
              - AR
              - KA
              - KO
              - HE
              - LV
              - UK
              - ID
              - MS
              - TH
              - ET
              - HR
              - LT
              - SK
              - SR
              - SL
              - VI
              - TL
              - IS
              - HI
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseListingMeta'
components:
  schemas:
    Bed:
      required:
        - bed_count
        - bed_type_id
      type: object
      properties:
        bed_type_id:
          type: integer
          format: int32
        bed_count:
          type: integer
          format: int32
    BedConfiguration:
      required:
        - beds
        - is_default_configuration
      type: object
      properties:
        beds:
          type: array
          items:
            $ref: '#/components/schemas/Bed'
        is_default_configuration:
          type: boolean
          description: >-
            Exactly one default bed configuration is mandatory for each room
            provided
      description: >
        <ul>

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

        <li>For single-room listing 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>
    Configuration:
      required:
        - listing_type_id
        - rooms
      type: object
      properties:
        listing_type_id:
          type: integer
          description: >
            <ul>

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

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

            </ul>
          format: int32
        rooms:
          type: array
          items:
            $ref: '#/components/schemas/Room'
    ExtraBedsConfigurationCreate:
      type: object
      properties:
        extra_beds:
          maximum: 100
          minimum: 0
          type: integer
          description: Number of extra beds you can provide
          format: int32
          default: 0
        cribs:
          maximum: 100
          minimum: 0
          type: integer
          description: Number of cribs you can provide
          format: int32
          default: 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>)?
          default: false
      description: Extra bed & crib options
    ListingCreate:
      required:
        - configuration
        - listing_name_id
      type: object
      properties:
        configuration:
          $ref: '#/components/schemas/Configuration'
        listing_name_id:
          type: integer
          description: >
            <ul>

            <li>Must exist in meta and be active in meta (see
            <code>$.listing_names</code>)</li>

            </ul>
          format: int32
        number_of_listings:
          type: integer
          description: Number of listings must be between 0 and 32000
          format: int32
          default: 1
        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 listing is located; 0 is a ground floor
          items:
            type: integer
            description: >-
              One or more floors where the listing is located; 0 is a ground
              floor
            format: int32
        occupancy:
          $ref: '#/components/schemas/OccupancyCreate'
        extra_beds_configuration:
          $ref: '#/components/schemas/ExtraBedsConfigurationCreate'
      description: >-
        Listing creation schema; use meta endpoint for fetching relevant meta
        data
    OccupancyCreate:
      type: object
      properties:
        max_guests:
          maximum: 50
          minimum: 1
          type: integer
          description: >-
            Maximum number of guests; must be less than or equal to sum of
            adults and children
          format: int32
          default: 1
        max_adults:
          maximum: 50
          minimum: 1
          type: integer
          description: >-
            Maximum number of adults; must be less than or equal to maximum
            number of guests
          format: int32
          default: 1
        max_children:
          maximum: 49
          minimum: 0
          type: integer
          description: >-
            Maximum number of children; must be less than maximum number of
            guests
          format: int32
          default: 0
        max_children_that_pay_children_rate:
          maximum: 49
          minimum: 0
          type: integer
          description: >-
            Maximum number of children eligible for the children rate (the rest
            are charged as adults), must be less than or equal to number of
            children
          format: int32
    Room:
      required:
        - type
      type: object
      properties:
        type:
          type: string
          description: >
            <ul>

            <li>For multi-room listings you must add one or more
            <code>BEDROOM_SUBROOM</code> and optionally one or more
            <code>LIVING_ROOM_SUBROOM</code></li>

            <li>For single-room listings 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'
    Size:
      required:
        - unit
        - value
      type: object
      properties:
        value:
          type: number
          description: Must be a value between 1 and 9999.99
          format: double
        unit:
          type: string
          description: SQM (square meters) or SQFT (square feet)
          enum:
            - SQM
            - SQFT
    ApiError:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        details:
          type: object
    ApiResponseListing:
      type: object
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          $ref: '#/components/schemas/Listing'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ExtraBedsConfiguration:
      required:
        - cribs
        - extra_beds
        - is_crib_and_extra_bed_allowed
      type: object
      properties:
        extra_beds:
          maximum: 100
          minimum: 0
          type: integer
          description: Number of extra beds you can provide
          format: int32
        cribs:
          maximum: 100
          minimum: 0
          type: integer
          description: Number of cribs you can provide
          format: int32
        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>)?
      description: Extra bed & crib options
    Listing:
      type: object
      properties:
        listing_id:
          type: integer
          format: int64
        configuration:
          $ref: '#/components/schemas/Configuration'
        listing_name_id:
          type: integer
          description: >
            <ul>

            <li>Must exist in meta and be active in meta (see
            <code>$.listing_names</code>)</li>

            </ul>
          format: int32
        number_of_listings:
          type: integer
          description: Number of listings must be between 0 and 32000
          format: int32
        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 listing is located; 0 is a ground floor
          items:
            type: integer
            description: >-
              One or more floors where the listing is located; 0 is a ground
              floor
            format: int32
        occupancy:
          $ref: '#/components/schemas/Occupancy'
        extra_beds_configuration:
          $ref: '#/components/schemas/ExtraBedsConfiguration'
        listing_name_fallback:
          type: string
          description: >-
            Contains listing name (EN_GB locale) for any listing name ID,
            including those missing in meta (for debug purposes only; read only)
      description: Listing schema; use meta endpoint for fetching relevant meta data
    Occupancy:
      required:
        - max_adults
        - max_children
        - max_children_that_pay_children_rate
        - max_guests
      type: object
      properties:
        max_guests:
          maximum: 50
          minimum: 1
          type: integer
          description: >-
            Maximum number of guests; must be less than or equal to sum of
            adults and children
          format: int32
        max_adults:
          maximum: 50
          minimum: 1
          type: integer
          description: >-
            Maximum number of adults; must be less than or equal to maximum
            number of guests
          format: int32
        max_children:
          maximum: 49
          minimum: 0
          type: integer
          description: >-
            Maximum number of children; must be less than maximum number of
            guests
          format: int32
        max_children_that_pay_children_rate:
          maximum: 49
          minimum: 0
          type: integer
          description: >-
            Maximum number of children eligible for the children rate (the rest
            are charged as adults), must be less than or equal to number of
            children
          format: int32
    ResponseMeta:
      type: object
      properties:
        ruid:
          type: string
    ApiResponseObject:
      type: object
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          type: object
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ApiResponseListListing:
      type: object
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ApiResponseListingMeta:
      type: object
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          $ref: '#/components/schemas/ListingMeta'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    BedType:
      type: object
      properties:
        bed_type_id:
          type: integer
          format: int32
        bed_type_name:
          type: string
        bed_type_description:
          type: string
        bed_type_description_imperial:
          type: string
        is_active:
          type: boolean
    ListingMeta:
      type: object
      properties:
        language_code:
          type: string
          enum:
            - EN_GB
            - EN_US
            - DE
            - NL
            - FR
            - ES
            - ES_AR
            - ES_MX
            - CA
            - IT
            - PT_PT
            - PT_BR
            - 'NO'
            - FI
            - SV
            - DA
            - CS
            - HU
            - RO
            - JA
            - ZH_CN
            - ZH_TW
            - PL
            - EL
            - RU
            - TR
            - BG
            - AR
            - KA
            - KO
            - HE
            - LV
            - UK
            - ID
            - MS
            - TH
            - ET
            - HR
            - LT
            - SK
            - SR
            - SL
            - VI
            - TL
            - IS
            - HI
        listing_types:
          type: array
          items:
            $ref: '#/components/schemas/ListingType'
        listing_names:
          type: array
          items:
            $ref: '#/components/schemas/ListingName'
        bed_types:
          type: array
          items:
            $ref: '#/components/schemas/BedType'
        property_categories:
          type: array
          items:
            $ref: '#/components/schemas/PropertyCategory'
    ListingName:
      type: object
      properties:
        listing_name_id:
          type: integer
          format: int32
        listing_name:
          type: string
    ListingType:
      type: object
      properties:
        listing_type_id:
          type: integer
          format: int32
        listing_type_name:
          type: string
        is_multi_room:
          type: boolean
        is_active:
          type: boolean
        valid_property_categories:
          type: array
          items:
            type: integer
            format: int32
        suggested_listing_names:
          type: array
          items:
            $ref: '#/components/schemas/ListingName'
    PropertyCategory:
      type: object
      properties:
        code:
          type: integer
          format: int32
        name:
          type: string
        code_ota:
          type: integer
          format: int32
        code_booking_extended:
          type: integer
          format: int32