Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.

Demand API (3.1)

Our Demand API offers a wide range of functionalities for affiliate partners to be able to retrieve data from Booking.com inventory.

- Based on basic REST principles, our endpoints return JSON data directly from our system.
- You can consume them directly through HTTPS calls, using the POST method.

Download OpenAPI description

demand-api.json

demand-api.yaml

Servers

Mock server

https://developers.booking.com/_mock/demand/docs/open-api/demand-api/

https://demandapi-sandbox.booking.com/3.1/

https://demandapi.booking.com/3.1/

accommodations

Endpoints and sections specific to the accommodations travel vertical: hotels, apartments, etc.

Operations

common/locations

Generic endpoints related with geographical locations: countries, cities, etc.

Operations

common/payments

Generic endpoints related to payments and finance: currencies, payment types, etc.

Operations

common

Operations

orders

Operations

Cancel an order

Request

Headers

X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json

orderstringrequired

ID of the order to cancel.

reasonstringrequired

The reason for cancelling this order.

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/orders/cancel \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "order": 509430129718799,
    "reason": "I would like to book another property instead of this one."
  }'

Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json

request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataobject

Response

application/json

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "status": "successful"
  }
}

Create an order

Request

Headers

X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json

accommodationobject

Additional information related to the accommodation order.

bookerobjectrequired

The booker's information.

booker.addressobjectrequired

The booker's address to be used for creating this order.

booker.address.address_linestringrequired

The details of this address.

booker.address.citystringrequired

The city for this address.

booker.address.countrystringrequired

The country for this address.

booker.address.post_codestringrequired

Post code for this address.

booker.companystring

The booker's company name.

booker.emailstringrequired

The booker's email address.

booker.languagestring^[a-z]{2}(-[a-z]{2})?$

An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: "nl" for Dutch/Nederlands or "en-us" for English (US). The full list can be obtained by calling common/languages.

Example:

"en-us"

booker.nameobjectrequired

The name of the booker.

booker.name.first_namestringrequired

booker.name.last_namestringrequired

booker.telephonestringrequired

The booker's telephone number.

order_tokenstringrequired

A token containing the necessary data to be used for creating this order.

paymentobjectrequired

Payment related information for the order.

payment.airplusobject

All information related to airplus payment. This is required if airplus is selected as payment method.

payment.business_informationobject

All business related information for billing and authorisation form. This must be included for the payments that require authorisation form.

payment.cardobject

Card information for executing the payment.

payment.include_receiptboolean

This is used to determine whether to include payment receipt_url in the response or not.

payment.methodstring

The payment method to be used for this order.

Enum"airplus""card""wallet"

payment.timingstringrequired

Information about when to execute the payment.

Enum"pay_at_the_property""pay_online_later""pay_online_now"

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/orders/create \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "accommodation": {
      "label": "Sample label",
      "products": [
        {
          "id": "333",
          "bed_configuration": "123456",
          "guests": [
            {
              "email": "test.name@booking.com",
              "name": "Test Name"
            }
          ]
        }
      ],
      "remarks": {
        "estimated_arrival_time": {
          "hour": 12
        },
        "special_requests": "We will need an extra cot."
      }
    },
    "booker": {
      "address": {
        "address_line": "Road-1, house-2",
        "city": "Amsterdam",
        "country": "NL",
        "post_code": "11111"
      },
      "company": "Booking B.V",
      "email": "test.name@booking.com",
      "language": "en-gb",
      "name": {
        "first_name": "Test",
        "last_name": "Name"
      },
      "telephone": "12345678"
    },
    "order_token": "sample-token",
    "payment": {
      "card": {
        "cardholder": "Test Name",
        "cvc": "111",
        "expiry_date": "2030-10",
        "number": "23333333333333"
      },
      "include_receipt": true,
      "method": "card",
      "timing": "pay_at_the_property"
    }
  }'

Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json

request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataobject

Response

application/json

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "accommodation": { … },
    "payment": { … }
  }
}

List orders

Request

This endpoint returns basic information for orders filtered according to the input.

Headers

X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json

One of:

updatedobjectrequired

Filtering orders by time range on basis of order "created" or "updated" time. Maximum time range is 7 days (1 week).

updated.fromstring(date-time)required

ISO 8601 timestamp in UTC, which indicates the timestamp from which you want to filter orders from (inclusive). The value should be within last 1 year.

updated.tostring(date-time)

ISO 8601 timestamp in UTC, which indicates the timestamp till which you want to filter orders to (inclusive). It has to be greater than or equal to "from".

currencystring^[A-Z]{3}$required

A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies. This input determines the currency used in the "booker_currency" fields in the output.

Example:

"EUR"

maximum_resultsintegermultiple of 10[ 10 .. 100 ]

The maximum number of results to return.

Default 100

sortobject

The sorting parameters for the response.

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/orders/details \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "created": {
      "from": "2023-02-28T02:00:00+00:00",
      "to": "2023-02-28T02:00:00+00:00"
    },
    "currency": "EUR",
    "maximum_results": 20,
    "sort": {
      "by": "updated",
      "direction": "descending"
    }
  }'

Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json

dataArray of objects

metadataobject

Metadata about the request.

request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

Response

application/json

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    { … }
  ],
  "metadata": {
    "next_page": null,
    "total_results": 1
  }
}

List accommodation for orders

Request

This endpoint returns all information for given accommodation orders

Bodyapplication/json

One of:

ordersArray of strings<= 100 itemsrequired

List of order IDs for which details should be returned.

currencystring^[A-Z]{3}$

A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.

Example:

"EUR"

extrasArray of strings

Input parameter to request for additional information about the accommodation order. It should be passed as a JSON array with one or more items.

Items Enum"accommodation_details""policies""extra_charges"

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/orders/details/accommodations \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "USD",
    "extras": [
      "accommodation_details",
      "policies",
      "extra_charges"
    ],
    "reservations": [
      2321873123,
      4666773123
    ]
  }'

Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json

request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataArray of objects

Response

application/json

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    { … }
  ]
}

Preview an order

Request

This endpoint returns the total price with final charges, as well as the price breakdown and payment/cancellation policies for each product passed in the input.

Headers

X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json

bookerobjectrequired

The booker's information.

booker.countrystring^[a-z]{2}$required

The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.

booker.platformstringrequired

The booker platform for showing the platform based deals and prices.

Enum"android""desktop""ios""mobile""tablet"

booker.travel_purposestring

The travel purpose of the booker.

Enum"business""leisure"

booker.user_groupsArray of strings

The user groups that the booker is a member of.

Items Value"authenticated"

currencystring^[A-Z]{3}$required

A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.

Example:

"EUR"

accommodationobjectrequired

Input parameter with the checkin and checkout date and all the accommodation products to be ordered.

accommodation.idinteger>= 1

A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling accommodations/details.

accommodation.checkinstring(date)

The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.

accommodation.checkoutstring(date)

The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.

accommodation.productsArray of objects

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/orders/preview \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "booker": {
      "country": "nl",
      "platform": "mobile",
      "travel_purpose": "leisure",
      "user_groups": [
        "genius2"
      ]
    },
    "currency": "EUR",
    "accommodation": {
      "id": 6745031,
      "checkin": "!START_DATE!",
      "checkout": "!END_DATE!",
      "products": [
        {
          "id": "674503106_275710478_0_2_0",
          "allocation": {
            "number_of_adults": 1,
            "children": [
              8
            ]
          }
        },
        {
          "id": "674503113_275710486_0_1_0",
          "allocation": {
            "number_of_adults": 1,
            "children": []
          }
        }
      ]
    }
  }'

Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json

request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataobject

Response

application/json

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "accommodation": { … },
    "order_token": "..."
  }
}

Demand API (3.1)

accommodations

common/locations

common/payments

common

orders

Cancel an order

Request

Responses

Was this helpful?

Create an order

Request

Responses

Was this helpful?

List orders

Request

Responses

Was this helpful?

List accommodation for orders

Request

Responses

Was this helpful?

Preview an order

Request

Responses

Was this helpful?