Booking.com Demand API

openapi: 3.1.0
info:
  title: Booking.com Demand API
  description: >-
    The Booking.com Demand API is a RESTful API that enables Affiliate Partners
    to access Booking.com's extensive travel inventory. It provides endpoints
    for searching accommodations such as hotels and apartments, checking
    availability, retrieving reviews, and getting detailed property information.
    The API uses JSON responses and requires HTTPS POST requests with Affiliate
    ID and Bearer token authentication. The latest version (V3.1) offers improved
    functionality and additional endpoints for building travel booking
    experiences including orders management, messaging, and payment information.
  version: '3.1'
  contact:
    name: Booking.com Developer Support
    url: https://developers.booking.com/demand/docs
  termsOfService: https://www.booking.com/content/terms.html
externalDocs:
  description: Booking.com Demand API Documentation
  url: https://developers.booking.com/demand/docs/open-api/demand-api
servers:
  - url: https://demandapi.booking.com/3.1
    description: Production Server
tags:
  - name: Accommodations
    description: >-
      Endpoints to search for stays such as hotels and apartments, check
      availability, retrieve reviews, and get detailed property information.
  - name: Constants
    description: >-
      Endpoints for retrieving reference data such as accommodation types,
      facility types, room types, and other enumerated values.
  - name: Conversations
    description: >-
      Endpoints to retrieve and manage messaging conversations, list
      conversations, fetch conversation details, and track updates.
  - name: Locations
    description: >-
      Endpoints for retrieving geographical location data including
      countries, cities, regions, and airports.
  - name: Messages
    description: >-
      Endpoints for two-way post-booking communication between guests and
      properties, allowing you to send and retrieve messages, exchange
      images, and check conversation details.
  - name: Orders
    description: >-
      Endpoints to preview and create new orders, check order details,
      cancel or modify existing orders.
  - name: Payments
    description: >-
      Generic payment-related endpoints, including supported currencies
      and payment types.
security:
  - bearerAuth: []
    affiliateId: []
paths:
  /accommodations/search:
    post:
      operationId: searchAccommodations
      summary: Search accommodations
      description: >-
        Returns the cheapest available product for each accommodation that
        matches the specified search criteria. When location filters such as
        country or region ID are applied, results are sorted by Booking.com
        popularity instead of price. Results include product availability,
        price, and charges by default.
      tags:
        - Accommodations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccommodationSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccommodationSearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accommodations/details:
    post:
      operationId: getAccommodationDetails
      summary: Get accommodation details
      description: >-
        Returns detailed information on all accommodation properties matching
        the given criteria including property descriptions, facilities, photos,
        location data, and policies.
      tags:
        - Accommodations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccommodationDetailsRequest'
      responses:
        '200':
          description: Accommodation details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccommodationDetailsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accommodations/availability:
    post:
      operationId: checkAccommodationAvailability
      summary: Check accommodation availability
      description: >-
        Checks availability for a specific accommodation, returning detailed
        product availability, pricing, and extra charges. The checkin date must
        be within 500 days and checkout must be between 1 and 90 days after
        checkin.
      tags:
        - Accommodations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccommodationAvailabilityRequest'
      responses:
        '200':
          description: Availability information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccommodationAvailabilityResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accommodations/bulk-availability:
    post:
      operationId: checkBulkAccommodationAvailability
      summary: Check multiple accommodation availability
      description: >-
        Checks availability for multiple accommodations at once. Accepts an
        array of accommodation IDs along with dates, guest information, and
        optional filters for meal plan and cancellation type.
      tags:
        - Accommodations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkAvailabilityRequest'
      responses:
        '200':
          description: Bulk availability results retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAvailabilityResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accommodations/reviews:
    post:
      operationId: getAccommodationReviews
      summary: Get accommodation reviews
      description: >-
        Retrieves traveler reviews for specified accommodations, providing
        feedback associated with particular properties. Reviews can be
        filtered by reviewer parameters and languages.
      tags:
        - Accommodations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccommodationReviewsRequest'
      responses:
        '200':
          description: Reviews retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccommodationReviewsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accommodations/reviews/scores:
    post:
      operationId: getAccommodationReviewScores
      summary: Get accommodation review scores
      description: >-
        Returns score distribution and score breakdown for the specified
        accommodations. The scores information can be filtered by reviewer
        parameters and languages.
      tags:
        - Accommodations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccommodationReviewScoresRequest'
      responses:
        '200':
          description: Review scores retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccommodationReviewScoresResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accommodations/chains:
    post:
      operationId: getAccommodationChains
      summary: Get accommodation chains
      description: >-
        Retrieves information about hotel chains and brand affiliations
        for accommodations listed on Booking.com.
      tags:
        - Accommodations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chain_ids:
                  type: array
                  description: List of chain IDs to retrieve
                  items:
                    type: integer
      responses:
        '200':
          description: Chain information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccommodationChainsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accommodations/constants:
    post:
      operationId: getAccommodationConstants
      summary: Get accommodation constants
      description: >-
        Retrieves reference data constants including accommodation types,
        accommodation facilities, accommodation themes, bed types, charge
        types, facility types, review scores, room facilities, and room types.
      tags:
        - Constants
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                constants:
                  type: array
                  description: >-
                    List of constant types to retrieve such as accommodation_types,
                    accommodation_facilities, bed_types, room_types, etc.
                  items:
                    type: string
                    enum:
                      - accommodation_facilities
                      - accommodation_themes
                      - accommodation_types
                      - bed_types
                      - charge_types
                      - facility_types
                      - review_scores
                      - room_facilities
                      - room_types
      responses:
        '200':
          description: Constants retrieved successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orders/preview:
    post:
      operationId: previewOrder
      summary: Preview an order
      description: >-
        Generates a preview of an order before creation, allowing the
        traveler to review the booking details, pricing, and policies
        before committing.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPreviewRequest'
      responses:
        '200':
          description: Order preview generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPreviewResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orders/create:
    post:
      operationId: createOrder
      summary: Create an order
      description: >-
        Creates a new booking order, allowing travelers to book and pay for
        travel services and products directly from the affiliate application.
        Manages bookings efficiently without redirecting users to Booking.com.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreateRequest'
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orders/details:
    post:
      operationId: getOrderDetails
      summary: Get order details
      description: >-
        Retrieves relevant booking details for a specific order, including
        status, pricing, guest information, and accommodation details.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderDetailsRequest'
      responses:
        '200':
          description: Order details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orders/cancel:
    post:
      operationId: cancelOrder
      summary: Cancel an order
      description: >-
        Processes the cancellation of an existing order. Cancellation policies
        and any applicable fees are determined by the property and rate plan.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCancelRequest'
      responses:
        '200':
          description: Order cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderCancelResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /messages/send:
    post:
      operationId: sendMessage
      summary: Send a message
      description: >-
        Sends a message within a conversation. The message body supports
        plain text and optionally allows attaching a file by referencing
        a previously uploaded attachment ID.
      tags:
        - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '200':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /messages/latest:
    post:
      operationId: fetchLatestMessages
      summary: Fetch latest messages
      description: >-
        Retrieves up to 100 of the most recent messages from a specified
        conversation, including messages from both property and guest,
        returned in reverse chronological order (newest first). Can be
        used to sync message threads or poll for updates.
      tags:
        - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchMessagesRequest'
      responses:
        '200':
          description: Messages retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchMessagesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /messages/latest/confirm:
    post:
      operationId: confirmMessages
      summary: Confirm message receipt
      description: >-
        Confirms receipt of specified messages. This confirmation is required
        before receiving new messages from the POST /messages/latest endpoint.
      tags:
        - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmMessagesRequest'
      responses:
        '200':
          description: Messages confirmed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmMessagesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/list:
    post:
      operationId: listConversations
      summary: List conversations
      description: >-
        Retrieves a list of messaging conversations, allowing you to browse
        and manage communication threads between guests and properties.
      tags:
        - Conversations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListConversationsRequest'
      responses:
        '200':
          description: Conversations listed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConversationsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/details:
    post:
      operationId: getConversationDetails
      summary: Get conversation details
      description: >-
        Fetches detailed information about a specific conversation, including
        participants, message count, and status.
      tags:
        - Conversations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationDetailsRequest'
      responses:
        '200':
          description: Conversation details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetailsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/currencies:
    post:
      operationId: getPaymentCurrencies
      summary: Get supported currencies
      description: >-
        Retrieves the list of currencies supported for payments on
        Booking.com, including currency codes and display information.
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Currencies retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrenciesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/types:
    post:
      operationId: getPaymentTypes
      summary: Get payment types
      description: >-
        Retrieves the list of payment types supported on Booking.com,
        including credit cards and other payment methods.
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Payment types retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTypesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /locations/countries:
    post:
      operationId: getCountries
      summary: Get countries
      description: >-
        Retrieves geographical location data for countries supported
        on Booking.com.
      tags:
        - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                countries:
                  type: array
                  description: List of country codes to filter by
                  items:
                    type: string
      responses:
        '200':
          description: Countries retrieved successfully
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /locations/cities:
    post:
      operationId: getCities
      summary: Get cities
      description: >-
        Retrieves geographical location data for cities, including city
        identifiers used in accommodation search queries.
      tags:
        - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                city_ids:
                  type: array
                  description: List of city IDs to retrieve
                  items:
                    type: integer
                country:
                  type: string
                  description: Country code to filter cities
      responses:
        '200':
          description: Cities retrieved successfully
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /locations/regions:
    post:
      operationId: getRegions
      summary: Get regions
      description: >-
        Retrieves geographical location data for regions, including
        region identifiers used in accommodation search queries.
      tags:
        - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                region_ids:
                  type: array
                  description: List of region IDs to retrieve
                  items:
                    type: integer
                country:
                  type: string
                  description: Country code to filter regions
      responses:
        '200':
          description: Regions retrieved successfully
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication. Include your API key token in the
        Authorization header.
    affiliateId:
      type: apiKey
      in: header
      name: X-Affiliate-Id
      description: >-
        Your Booking.com Affiliate ID, required with every request.
  schemas:
    Booker:
      type: object
      description: Information about the person making the booking
      properties:
        country:
          type: string
          description: Two-letter country code of the booker
          example: nl
        platform:
          type: string
          description: Platform the booker is using
          enum:
            - desktop
            - mobile
            - tablet
          example: desktop
    Guests:
      type: object
      description: Guest allocation for the search or booking
      required:
        - number_of_adults
        - number_of_rooms
      properties:
        number_of_adults:
          type: integer
          description: Number of adult guests
          minimum: 1
          example: 2
        number_of_rooms:
          type: integer
          description: Number of rooms needed
          minimum: 1
          example: 1
        children_ages:
          type: array
          description: Ages of children traveling
          items:
            type: integer
            minimum: 0
            maximum: 17
    AccommodationSearchRequest:
      type: object
      required:
        - booker
        - checkin
        - checkout
        - guests
      properties:
        booker:
          $ref: '#/components/schemas/Booker'
        checkin:
          type: string
          format: date
          description: >-
            Check-in date in yyyy-mm-dd format. Must be within 500 days
            in the future.
        checkout:
          type: string
          format: date
          description: >-
            Check-out date in yyyy-mm-dd format. Must be between 1 and 90
            days after checkin and within 500 days in the future.
        city:
          type: integer
          description: City identifier for location-based search
          example: -2140479
        country:
          type: string
          description: Country code to filter by
        region:
          type: integer
          description: Region identifier for location-based search
        accommodation_ids:
          type: array
          description: Specific accommodation IDs to search
          items:
            type: integer
        guests:
          $ref: '#/components/schemas/Guests'
        extras:
          type: array
          description: Additional data to include in the response
          items:
            type: string
            enum:
              - extra_charges
              - products
        filters:
          type: object
          description: Filters to narrow search results
          properties:
            meal_plan:
              type: string
              description: Filter by meal plan type
            cancellation_type:
              type: string
              description: Filter by cancellation policy type
    AccommodationSearchResponse:
      type: object
      properties:
        result:
          type: array
          description: List of matching accommodations
          items:
            $ref: '#/components/schemas/AccommodationSearchResult'
    AccommodationSearchResult:
      type: object
      properties:
        accommodation_id:
          type: integer
          description: Unique identifier for the accommodation
        name:
          type: string
          description: Name of the accommodation
        city:
          type: string
          description: City where the accommodation is located
        country:
          type: string
          description: Country code of the accommodation
        price:
          $ref: '#/components/schemas/Price'
        products:
          type: array
          description: Available products/rooms
          items:
            $ref: '#/components/schemas/Product'
    AccommodationDetailsRequest:
      type: object
      required:
        - accommodation_ids
      properties:
        accommodation_ids:
          type: array
          description: List of accommodation IDs to retrieve details for
          items:
            type: integer
        extras:
          type: array
          description: Additional detail categories to include
          items:
            type: string
    AccommodationDetailsResponse:
      type: object
      properties:
        result:
          type: array
          description: List of accommodation details
          items:
            $ref: '#/components/schemas/AccommodationDetail'
    AccommodationDetail:
      type: object
      properties:
        accommodation_id:
          type: integer
          description: Unique identifier for the accommodation
        name:
          type: string
          description: Name of the accommodation
        description:
          type: string
          description: Detailed description of the accommo

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/booking-com/refs/heads/main/openapi/booking-com-demand-api-openapi.yml