Last updated

Try it out!

If you are a Booking.com Managed Affiliated Partner you can start trying our Demand API in your client application.

Accommodations quick guide

Follow this quick guide with a basic use case to learn how to use our /accommodation endpoints and how to integrate them with your client application so that a traveller can:

  • Search for accommodations provided by Booking.com.
  • Look at detailed information about an accommodation, including real-time room availability and pricing.
  • Book their accommodation either via your website or directly through Booking.com.

Refer to the Car Rental Quick guide for initial instructions on how to use car rental endpoints.

You can handle the traveller bookings in one out of the two ways we offer, depending on the integration type you are implementing:

  • The Search and look integration redirects the traveller to Booking.com to make the booking.
  • The Search, look and book integration covers all the process, including the booking directly in your application by means of the /orders endpoints.
Important

The Search, look and book integration enables you to complete customer transactions on your website. For this type of integration, you require approval, a sound business case and an appropriate partner agreement with Booking.com.

This diagram shows the endpoints that you must use for each integration type, depending on the traveller needs.

Getting Started Steps

Before you start

Before start trying out our Demand API, make sure that:

Checklist
☑You are a registered Booking.com Managed Affiliate Partner.
☑Your dedicated Account Manager has granted you access to Partner Centre (after signing agreed contract).

☑

From the Partner Centre you have generated:

  • A valid API key that allows you to use the endpoints.

  • An unique identifier id (X-Affiliate-Id) that identifies your requests.

☑You have a suitable API testing tool, such as cURL or Postman.

Use case

The given use case represent a typical Demand API scenario:

A traveller visits your website to find somewhere to stay in Amsterdam.
They want to book a 2-night stay, for 2 adults with no children, and they want 1 room.
The traveller is in the Netherlands and is using your website from their mobile phone.

To get familiar with the full booking process and the endpoints involved, take this use case as an example in every step of the guide.

Attention

Do not forget to authenticate every call that you make to a Demand API endpoint by using your generated API key - Token and your X-Affiliate-Id parameter. For more information, see the Authentication and authorisation section.

Steps - Search and look

Step 1 - Search for matching accommodations

To find properties that match the use case search criteria:

→ Use the accommodations/search endpoint.

Create the search request body with the following fields:

Key parameters
citySpecify the unique city id for the required destination.
  • Get your city id using the List cities endpoint.
  • In this case for the use case provided, use the one assigned to Amsterdam -2140479.

booker.country

Specify the country from which the search request is made.

  • Get your two-letter country code using the List countries endpoint.
  • In this case for the use case provided, use (nl).
  • This is required to ensure that the response complies with relevant laws on the display of taxes and fees.
Note

The country code must always be in lowercase.

booker.platformSpecify the platform from which the search request is made.
  • In this case, for the use case provided, use (mobile).
  • This is required so that any platform-based prices and deals can be returned correctly.
checkin/checkoutSpecify the traveller's requested arrival and departure dates (use the YYYY-MM-DD format).
guestsSpecify the number of rooms the traveller needs (1), and the number of adults for the stay (2).

For the provided use case you should create a request body similar to this example:

{
  "city": -2140479,
  "booker": {
    "country": "nl",
    "platform": "mobile"
  },
  "checkin": "2023-11-06",
  "checkout": "2023-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}

→ Try it yourself

Step 2 - Get details of matching accommodations

Before you show the search results to the traveller you need to get some more information about each accommodation.

→ Call /accommodations/details to get additional data about the properties returned in the previous search response.

To get details about a specific accommodation:

  1. Go to the accommodations/search response.

  2. Copy the returned accommodation’s unique identifier id.

  3. Use it in your /accommodations/details request.

  4. The returned response provides all the details about the selected accommodation.

    Your request body should look like this:

{
  "accommodations": [
    10507360
  ],
  "extras": [
    "description",
    "facilities",
    "rooms"
  ],
  "languages": [
    "en-gb"
  ]
}

genius-bulb You can optionally remove or include categories from the extras field to narrow down your response: description, facilities, payment, photos, policies, rooms.

→ Try it yourself

Step 3 - Display your search results page

You now have the necessary information to display the search results to the traveller.

→ Select the data from the accommodations/search and /accommodations/details responses (Step 1 and Step 2) to provide the level of information that is needed for your particular business scenario.

genius-bulb Use the extras field to retrieve more details about some or all of the given categories. For example, if you want to use a photograph in your search results, add the field "extras": ["photos"] to your request.

{
  ...
  {
    "accommodations": [
      1466774
    ],
    "extras": [
      "photos"
    ],
    "languages": [
      "en-gb"
    ]
  },
  ...
}

The traveller browses through the search results, looking for properties where they might like to stay.
They like the look of the "Demand API Sandbox Hotel Orion".
Now they want to see more details about the hotel and the full list of available rooms and prices.

Step 4 - Get the accommodation's availability and prices

→ Use the Get the accommodation's availability endpoint to provide real-time information about the availability and prices of all rooms offered by the selected accommodation.

To retrieve the availability and prices of a specific accommodation:

  1. Go to the accommodations/search response (in step 1).

  2. And copy:

    • The returned accommodation’s unique identifier id
    • The values used for booker, checkin, checkout, and guestsin your search request (Refer to step 1).

  3. Paste same values into your /accommodations/availability request.

Your request body should look like this:

{
  "accommodation": 10507360,
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "checkin": "2023-11-06",
  "checkout": "2023-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}

→ (Try it yourself)

Step 5 - Display your product page

You can now show the traveller complete details of the accommodation they want to look at, including real-time product availability and prices.

→ Select the data from your /accommodations/details and /accommodations/availability responses (in step 3 and 4) to provide the appropriate level of information for your particular business scenario.

After browsing the details of the "Demand API Sandbox Hotel Orion", the traveller decides to book the recommended product.

Steps - The booking

Follow different instructions depending on your integration type:

Search and look integration

If you are using a Search and look integration, you cannot process bookings directly.

However, you can still process and receive commission on bookings by redirecting travellers to the Booking.com website, so that they can make their booking there.

Redirect travellers to Booking.com

When a traveller has chosen the product(s) that they want to book, redirect them to the url returned in your /accommodations/availability response.

The url contains your affiliate id (aid), so that the booking can be attributed to you.

For example:

...
   "url": "https://www.booking.com/<SELECTED_ACCOMMODATION>.html?aid=xxxxx&checkin=2025-11-06&checkout=2025-11-08&no_rooms=1&group_adults=2&mcid=10"
...

The Booking.com website displays the accommodation page for the traveller's chosen accommodation:

  • The Search box shows the traveller's search criteria.
  • In the Availability section, the details for the traveller's selected product are shown at the top of the list together with the recommended option.

Search, look and book integration

To process bookings directly in your application you must use the Search, look and book integration type.

Step 1 - Preview the order

You can process the bookings directly in your application using the /orders endpoints.

→ Call /orders/preview to get final details of the accommodation and products the traveller is about to book, what they will have to pay, when and how they can pay it, and the applicable cancellation terms.

Orders/preview request

To construct the orders/preview request, follow these steps:

  1. Go to the /accommodations/availability request (in step 4).
  2. And copy the used values:
✓The value used for booker.platform-- in this case mobile.
✓The booker.country (nl)
✓currency-- Use EUR, because the traveller in the example is using your website from the Netherlands.
✓The accommodation’s unique identifier id
✓The used checkin and checkout dates.
  1. Paste same values into your /orders/preview request.
  2. Go to the /accommodations/availability response (in step 4)
  3. Copy the following returned values:
✓recommendation.products.idThis is the id of the most affordable product that meets the search and availability criteria -- In this case 1050736002_377311511_0_2_0.
✓allocation.number_of_adultsSpecify the number of adults who will stay in the room used in the product -- In this case, use the recommendation.products.number_of_adults value (2)
  1. Paste all the previously copied values into your /orders/preview request.

Your request body should look like this example.

{
  "booker": {
    "platform": "mobile",
    "country": "nl"
  },
  "currency": "EUR",
  "accommodation": {
    "id": 10507360,
    "checkin": "2023-11-06",
    "checkout": "2023-11-08",
    "products": [
      {
        "id": "1050736002_377311511_0_2_0",
        "allocation": {
          "number_of_adults": 2
        }
      }
    ]
  }
}

→ Try it yourself

Orders/preview response

The response contains the following information about the order:

General policies
**general_policies**
In the exampleReferences
paymentIt shows when and how the traveller can pay for the order.In the example, the traveller must pay_online_now, using any of the indicated payment cards (Cards are shown by their id).
priceIt gives a detailed breakdown of what the traveller must pay for the order.In the example, the total price (in EUR) of the order is 184. This comprises:
  • A base price of 165.14
  • Two extra_charges (are shown by their charge id which is 21 and 22) of 14.86 for VAT and 4.00 for city tax, respectively.
For more information about the individual components of the price object, see Accommodation pricing guide.

Example of general_policies.payment:

{
  ...
  "accommodation": {
    "id": 10507360,
    "currency": {
      "accommodation": "EUR",
      "booker": "EUR"
    },
    "general_policies": {
      "payment": {
        "pay_at_the_property": null,
        "pay_online_later": null,
        "pay_online_now": {
          ...
          "methods": {
            ...
            "cards": [
              1,
              4,
              5,
              11,
              ...
            ]
          }
        }
      }
    }
  },
  ...
}

Example of general_policies.price:

{
  ...
  "accommodation": {
    "id": 10507360,
    "currency": {
      "accommodation": "EUR",
      "booker": "EUR"
    },
    ...
    "price": {
      "base": {
        "accommodation_currency": 165.14,
        "booker_currency": 165.14
      },
      "extra_charges": {
        "conditional": [],
        "non_conditional": [
          {
            "charge": 21,
            "total_amount": {
              "accommodation_
Accommodation products

For each product in the order the accommodation.products object displayes:

accommodation.products
In the exampleReferences
policiesFor each product in the order, it shows the details of the cancellation and meal_plan policies.In the following example, the product does not include any meals or any free cancellation period. In the event of cancellation, a fee of 180 EUR (the total price minus the city tax) applies from the moment of booking.Refer to the cancellation policies section for detailed examples.
priceGives a detailed breakdown of what the traveller needs to pay for the product, including a full breakdown of the charges.In the following example (althought it is very similar to the previous one), you can see that the city tax (22) is levied on a per_person_per_night basis, at a rate of 1.00 EUR.For more information about the individual components of the price object, see the Accommodation pricing guide.

Example for accommodation.products.price

{
  ...
  "accommodation": {
    "id": 10507360,
    "currency": {
      "accommodation": "EUR",
      "booker": "EUR"
    },
    ...
    "products": [
      {
        "id": "1050736002_377311511_0_2_0",
        ...
        "price": {
          "base": {
            "accommodation_currency": 165.14,
            "booker_currency": 165.14
          },
          "extra_charges": {
            "conditional": [],
            "non_conditional": [
              {
                "charge": 22,
                "mode": "per_person_per_night",
                "percentage": null,
                "total_amount": {
                  "accommodation_currency": 4.00,
                  "booker_currency": 4.00
                },
                "unit_amount": {
                  "accommodation_currency": 1.00,
                  "booker_currency": 1.00
                }
              },
              {
                "charge": 21,
                "mode": "percentage",
                "percentage": 9.00,
                "total_amount": {
                  "accommodation_currency": 14.86,
                  "booker_currency": 14.86
                },
                "unit_amount": {
                  "accommodation_currency": null,
                  "booker_currency": null
                }
              }
            ]
          },
          "total": {
            "accommodation_currency": 184.00,
            "booker_currency": 184.00
          }
        }
      }
    ]
  },
  ...
}

Example for accommodation.products.policies

{
  ...
  "accommodation": {
    "id": 10507360,
    "currency": {
      "accommodation": "EUR",
      "booker": "EUR"
    },
    ...
    "products": [
      {
        "id": "1050736002_377311511_0_2_0",
        "policies": {
          "cancellation": [
            {
              "from": "now",
              "price": {
                "accommodation_currency": 180.00,
                "booker_currency": 180.00
              }
            }
          ],
          "meal_plan": {
            "meals": [],
            "plan": "no_plan"
          }
        }
      }
    ]
  },
  ...
}
Order token

A order_token is also returned in the orders/preview response. This contains encapsulated details about the order.

  • Using this token reduces the risk of data mismatch errors between the endpoints and provides a more efficient booking experience.

Copy it, as you will need it for the next step.

Attention

The order_token expires after 15 minutes. You must therefore call /orders/create within this time window.

{
  ...
  "accommodation": {
    "id": 10507360,
    ...
    "order_token": "eyJhbGciOiJIUzI1NiJ9.eyJ....<truncated for display in this example>...QytoS0yU"
  },
  ...
}
Step 2 - Display your order preview page

  • You can now show the traveller final details of what they are booking, what they will have to pay, when and how they can pay it, and the cancellation terms that will apply.

  • You should also gather any other information needed from the traveller to complete the order - for example, guest details for rooms, estimated arrival times or special requests.

→ Select the data from your /orders/preview response to provide the appropriate information on your preview page.

After checking the details of the order, the traveller supplies their payment information and any other needed information, and proceeds with the booking.

Step 3 - Create the order

→ Call /orders/create to process the payment and make the reservation with the accommodation.

Use the following fields to construct the request body:

  • booker: Specify the address, email, name and telephone number details of the person who is making the booking (the traveller, in this example).
  • order_token: Use the order_token returned in the /orders/preview response.
    • Pass this token to the /orders/create request.
    • Using this token reduces the risk of data mismatch errors between the endpoints and provides a more efficient booking experience.

In the payment object:

  • card: Specify the card details provided by the traveller.
  • include_receipt: Set to true to generate a receipt that you can provide to the traveller.
  • method: Specify the payment method, in this case "card".
  • timing: Choose pay_online_now, as this is the only supported option for the selected product.

Your request body should look like this example.

curl -i -X POST \
  https://demandapi.booking.com/3.1/orders/create \
  -H 'Content-Type: application/json' \
  -d '{
    "accommodation": {
      "label": "Sample label",
      "products": [
        {
          "id": "333",
          "bed_configuration": "123456",
          "guests": [
            {...}
          ]
        }
      ],
      "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"
    }
  }'

→ Try it yourself

Curious to know more?
Previous page
Next page