booking-com Orders API

openapi: 3.1.0
info:
  title: Booking.com Car Rentals Accommodations Orders API
  description: The Booking.com Car Rentals API is part of the Demand API and provides endpoints specific to the car rental segment of the connected trip experience. Developers can use it to search for available car rentals, retrieve car details, look up depots and suppliers, and access depot review scores. The API enables affiliate partners to integrate Booking.com's car rental inventory into their own platforms, offering users the ability to find and book vehicles as part of their travel planning workflow.
  version: '3.1'
  contact:
    name: Booking.com Developer Support
    url: https://developers.booking.com/demand/docs
  termsOfService: https://www.booking.com/content/terms.html
servers:
- url: https://demandapi.booking.com/3.1
  description: Production Server
security:
- bearerAuth: []
  affiliateId: []
tags:
- name: Orders
  description: Endpoints to preview and create new orders, check order details, cancel or modify existing orders.
paths:
  /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'
components:
  schemas:
    OrderCreateRequest:
      type: object
      required:
      - accommodation_id
      - booker
      - checkin
      - checkout
      - guests
      - products
      - payment
      properties:
        accommodation_id:
          type: integer
          description: Accommodation to book
        booker:
          allOf:
          - $ref: '#/components/schemas/Booker'
          - type: object
            properties:
              first_name:
                type: string
                description: Booker first name
              last_name:
                type: string
                description: Booker last name
              email:
                type: string
                format: email
                description: Booker email address
              telephone:
                type: string
                description: Booker telephone number
        checkin:
          type: string
          format: date
          description: Check-in date
        checkout:
          type: string
          format: date
          description: Check-out date
        guests:
          $ref: '#/components/schemas/Guests'
        products:
          type: array
          description: Products to book
          items:
            $ref: '#/components/schemas/ProductSelection'
        payment:
          $ref: '#/components/schemas/PaymentInfo'
    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
    OrderDetailsRequest:
      type: object
      required:
      - order_id
      properties:
        order_id:
          type: string
          description: Unique identifier of the order to retrieve
    Order:
      type: object
      properties:
        order_id:
          type: string
          description: Unique order identifier
        status:
          type: string
          description: Current order status
          enum:
          - confirmed
          - cancelled
          - pending
        accommodation_id:
          type: integer
          description: Booked accommodation ID
        checkin:
          type: string
          format: date
          description: Check-in date
        checkout:
          type: string
          format: date
          description: Check-out date
        total_price:
          $ref: '#/components/schemas/Price'
        booker:
          type: object
          description: Booker information
          properties:
            first_name:
              type: string
              description: Booker first name
            last_name:
              type: string
              description: Booker last name
            email:
              type: string
              description: Booker email
        products:
          type: array
          description: Booked products
          items:
            $ref: '#/components/schemas/Product'
        created_at:
          type: string
          format: date-time
          description: Order creation timestamp
    OrderPreviewRequest:
      type: object
      required:
      - accommodation_id
      - booker
      - checkin
      - checkout
      - guests
      - products
      properties:
        accommodation_id:
          type: integer
          description: Accommodation to book
        booker:
          $ref: '#/components/schemas/Booker'
        checkin:
          type: string
          format: date
          description: Check-in date
        checkout:
          type: string
          format: date
          description: Check-out date
        guests:
          $ref: '#/components/schemas/Guests'
        products:
          type: array
          description: Products to include in the order
          items:
            $ref: '#/components/schemas/ProductSelection'
    OrderPreviewResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/OrderPreview'
    ProductSelection:
      type: object
      description: A product selected for booking
      required:
      - product_id
      properties:
        product_id:
          type: string
          description: Product identifier from availability results
        quantity:
          type: integer
          description: Number of this product to book
          minimum: 1
    Price:
      type: object
      description: Price information
      properties:
        amount:
          type: number
          description: Price amount
        currency:
          type: string
          description: ISO 4217 currency code
    OrderCancelResponse:
      type: object
      properties:
        result:
          type: object
          properties:
            order_id:
              type: string
              description: Cancelled order identifier
            status:
              type: string
              description: New order status
              enum:
              - cancelled
            cancellation_fee:
              $ref: '#/components/schemas/Price'
    PaymentInfo:
      type: object
      description: Payment details for order creation
      properties:
        payment_type:
          type: string
          description: Payment method type
        card_number:
          type: string
          description: Credit card number
        expiry_date:
          type: string
          description: Card expiry date
        cvc:
          type: string
          description: Card verification code
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        errors:
          type: array
          description: List of errors
          items:
            type: object
            properties:
              code:
                type: string
                description: Error code
              message:
                type: string
                description: Human-readable error message
    OrderCancelRequest:
      type: object
      required:
      - order_id
      properties:
        order_id:
          type: string
          description: Unique identifier of the order to cancel
    OrderResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/Order'
    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
    OrderPreview:
      type: object
      properties:
        total_price:
          $ref: '#/components/schemas/Price'
        cancellation_policy:
          type: string
          description: Cancellation policy details
        products:
          type: array
          description: Products in the preview
          items:
            $ref: '#/components/schemas/Product'
    Product:
      type: object
      description: An available room or product at an accommodation
      properties:
        product_id:
          type: string
          description: Unique product identifier
        room_name:
          type: string
          description: Name of the room type
        meal_plan:
          type: string
          description: Included meal plan
        cancellation_type:
          type: string
          description: Cancellation policy type
        price:
          $ref: '#/components/schemas/Price'
  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.
externalDocs:
  description: Booking.com Car Rentals API Documentation
  url: https://developers.booking.com/demand/docs/open-api/demand-api/cars