Accommodation tutorial

Follow this end to end tutorial to learn how to use our /accommodation endpoints and how to integrate them with your client application.

This end to end tutorial offers a step-by-step explanation with examples on how to use our /accommodation endpoints in different integration flows, so you can integrate them with your client application

⏱️ Estimated time to complete: 30 - 45 minutes

Purpose: Complete step-by-step scenario from search to booking with explanations.
Who this is for: Managed Affiliated Partner that want to see how all endpoints connect in a real booking flow.
What you´ll build: An end‑to‑end flow so a traveller can search accommodations, inspect details & live prices, and either (A) be redirected to Booking.com to book, or (B) complete the booking in your app (partner approval required).
Content:
1. Search & Look flow
2. Search, Look & Book flow
Code samples: Full request/response bodies with annotations and use case context.

What you’ll learn

How to call the /accommodations endpoints to search and fetch property details.
How to retrieve real‑time availability & prices and present a recommended option.

How to implement two booking paths (depending on your integration type):

Search & look (redirect to Booking.com to make the booking)
Search, look & book (create the order in your app by means of the /orders endpoints, requires approval).

Before you start

Before you start, make sure you’ve completed the prerequisites. You’ll need:

✓ A valid API key token.
✓ Your X-Affiliate-Id
✓ Open the try out console.
✓ Use the sandbox environment.

Use case

The given use case represent a typical Accommodation 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.

Authenticate every request

Include your API key token and your X-Affiliate-Id on the calls. See the Authentication and authorisation section.

Integration overview

You can implement one of two integration types:

Search & look - You redirect the traveller to Booking.com to book.
Search, look & book - You complete the booking in your app using the /orders endpoints.

Important

Search, look & book requires approval, a sound business case, and an appropriate partner agreement with Booking.com.

The following diagram shows the endpoints involved for each integration path:

Getting Started Steps

Steps - Search and look

Step 1 - Search for matching accommodations

→ Use the accommodations/search endpoint to find properties.

Create the search request body with the following fields to match the scenario:

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

City and country lookup

Use the location cities and countries endpoints to resolve the IDs and ISO‑2 codes.
Country codes must be lowercase (e.g., nl).

→ Try it yourself

Step 2 - Get details of selected accommodations

Before you show 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:

Go to the accommodations/search response.
Copy the returned accommodation’s unique identifier id.
Use it in your /accommodations/details request.
The returned response provides all the details about the selected accommodation.

Example:

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

You can optionally use the extras field to include only what you need: description, facilities, payment, photos, policies, rooms. For example, if you want to use a photograph in your search results, add the field "extras": ["photos"] to your request.

→ Try it yourself

Step 3 - Display your search results page

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

→ Combine key fields from Search and Details (Step 1 and Step 2) to render your list:

Recommended essentials per product:

Property name and location
Primary photo (if requested via extras)
Meal prices.
Ratings and reviews.
Deep link/URL for the booking path you support.

The traveller reviews the search list and selects 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 real-time availability and prices

→ Use the accommodation's availability endpoint using the same criteria as the search.

To retrieve the availability and prices of a specific accommodation:

Go to the accommodations/search response (step 1).
And copy:
- The returned accommodation id
- The values used for booker, checkin, checkout, and guests in your search request.
Paste same values into your /accommodations/availability request.

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

→ (Try it yourself)

Step 5 - Display the product in property page

Show the traveller full details for the selected accommodation, including live products and prices from Step 4 and rich content from Step 2.

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:

Redirect to Booking.com (Search and look integration)

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

Redirect the traveller to the url (web) or deep_link_url (app) from the /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 traveller can proceed the payment and confirm the booking from there.

Create the order in your app (Search, look & book)

To process bookings directly in your application you must use the /orders API collection.

Important

Requires approval and partner agreement.

Step 1 - Preview the order

→ Call /orders/preview to confirm final details (what’s being booked, what will be paid, when/how, and cancellation terms).

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

Go to the /accommodations/availability request (in step 4) and copy the used values:

✓ booker.platform- in this case mobile.

✓ booker.country (nl), because the traveller in the example is using your website from the Netherlands.

✓ currency- EUR

✓ Accommodation id (10507360) and checkin and checkout dates.

Paste same values into your /orders/preview request.
Go to the /accommodations/availability response (in step 4)
Copy the following returned values:

✓ recommendation.products.id - This is the id of the most affordable product that meets the search and availability criteria (in example 1050736002_377311511_0_2_0).

✓ allocation.number_of_adults - Specify 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)

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": "2025-11-06",
    "checkout": "2025-11-08",
    "products": [
      {
        "id": "1050736002_377311511_0_2_0",
        "allocation": {
          "number_of_adults": 2
        }
      }
    ]
  }
}

→ Try it yourself

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?

Check the Orders section for more tips on how to preview and create your order requests.
Learn more about all Payment methods.
For examples and instructions on different payment flows, refer to Payments quick guide.
Refer to Payments - Use cases section for more details on how to set orders for different payment scenarios.

Accommodation tutorial

What you’ll learn

Before you start

Use case

Integration overview

Steps - Search and look

Steps - The booking

Redirect to Booking.com (Search and look integration)

Create the order in your app (Search, look & book)

Was this helpful?