Skip to content
ACCOMMODATION/
/
Version 3.2 and 3.3
Last updated

Search, look and book tutorial

Follow this end-to-end tutorial to build a complete Search, look and book integration for accommodation using Demand API.

v3.3 v3.2

⏱️ Estimated time to complete: 30 - 45 minutes

What you’ll learn

  • How to search for accommodations and retrieve property details.
  • How to check real-time availability and prices for a selected property.
  • How to display accommodation options to travellers.
  • How to implement the booking flow in your platform.

Before you start

Complete the Demand API prerequisites. You’ll need:

Approval required

The full Search, look and book flow explained in this guide requires Booking.com approval and an appropriate partner agreement. Confirm that this integration flow is enabled for your account before implementing it.

Use case

This tutorial follows a typical accommodation search, look and book:

A traveller is looking for a two-night stay in Amsterdam for two adults in one room. The booker is in the Netherlands and is using a mobile device. When the traveller finds the property that matches their needs, places the order from your platform.

Use this scenario throughout the examples. Replace the dates and other values with the traveller’s actual search details.

Search, look and book flow overview

The following diagram shows the endpoints involved for the Search, look and book flow:

Getting Started Steps

Steps - Search and look

Step 1 - Search for matching accommodations

→ Use the accommodations/search endpoint to find accommodations that match the traveller’s destination, dates, guest allocation and other criteria.

The request requires the booker’s country and platform, check-in and check-out dates, and guest information.

This example searches Amsterdam for two adults in one room.

{
  "city": -2140479,
  "booker": {
    "country": "nl",
    "platform": "mobile"
  },
  "checkin": "2027-11-06",
  "checkout": "2027-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

The search result is a starting point for comparing properties. Retrieve live availability and prices for the selected accommodation before presenting bookable products.

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.

→ Use /accommodations/details to retrieve static information about the selected property. Availability and pricing are returned by /accommodations/availability.

  1. Pass the accommodation ID returned by the search.
  2. Use extras to request the additional fields your application needs.
  3. Use languages to specify the languages for localised content.

Example:

{
  "accommodations": [
    10004
  ],
  "extras": [
    "description",
    "facilities",
    "payment",
    "photos",
    "policies",
    "rooms"
  ],
  "languages": [
    "en-gb"
  ]
}

genius-bulb You can also request bundles in extras. Request only the data you need; an empty or omitted extras value returns core property details.

Try it yourself

genius-bulb Use the property information that helps travellers decide whether to continue. For example, you can request photos for search cards and request rooms and policies when a traveller opens a property page. See Look up accommodation details for field descriptions and display guidance.

Step 3 - Display search results page

Combine the search response with the property details to build the results list. You can display:
  • Property name and location.
  • A primary photo, if requested.
  • The search price and currency.
  • The review score and number of reviews, where available.
  • The web or app link for the redirect flow you support.

Review scores are based on traveller traffic across Booking.com and may not represent your own customers’ experience.

If you display these scores or reviews, make sure travellers are informed what they represent. See /accommodations/reviews for the applicable guidance.

The traveller selects a property and opens its details page to compare available rooms and prices.

Step 4 - Get real-time availability and prices

→ Use /accommodations/availability to retrieve current availability, prices, charges and policies for the selected property.

You can request details for up to 50 accommodation IDs at a time.

Use the same booker, dates and guest allocation as in the search request.

Pass the selected accommodation ID in the accommodations array.

{
  "accommodations": [
    10004
  ],
  "booker": {
    "country": "nl",
    "platform": "mobile"
  },
  "checkin": "2027-11-06",
  "checkout": "2027-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  },
  "extras": [
    "extra_charges"
  ]
}

Try it yourself

Step 5 - Display the product in property page

Combine the live products and prices from Step 4 with the static content from Step 2. * Show the traveller the details needed to choose a product, including the room, occupancy, price, meal plan, cancellation terms and payment timing. * Make the total price and applicable charges clear. Do not treat a product as bookable based only on the earlier search response; use the current availability response.

After browsing the details of the accommodation, the traveller selects a product and continues to booking.

Steps - Create the order in your platform (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 validate the selected products and retrieve the current price, policies and payment options before asking the traveller to confirm.

Use the accommodation ID, dates, booker details and product IDs from the availability response.

For each product, provide the allocation returned in the recommendation or the traveller’s chosen allocation.

{
  "currency": "EUR",
  "accommodation": {
    "id": 10004,
    "booker": {
      "country": "nl",
      "platform": "mobile",
      "travel_purpose": "leisure"
    },
    "checkin": "2027-11-06",
    "checkout": "2027-11-08",
    "products": [
      {
        "id": "1000420_95127794_2_0_0",
        "allocation": {
          "number_of_adults": 2,
          "children": []
        }
      }
    ]
  }
}

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 confirms the preview and provide their payment information together with any other needed details.

Step 3 - Create the order

→ Call /orders/create with the order_token returned by /orders/preview and the required booker, guest and payment details.

This example assumes that the preview allows the traveller to pay online now by card.

  • In your request, use a payment timing and method supported by the preview response.
  • Provide the details required for the selected payment flow.
{
  "accommodation": {
    "products": [
      {
        "id": "1000420_95127794_2_0_0",
        "guests": [
          {
            "name": "Jane Doe",
            "email": "jane.doe@example.com"
          }
        ]
      }
    ]
  },
  "booker": {
    "address": {
      "address_line": "1 Example Street",
      "city": "Amsterdam",
      "country": "nl",
      "post_code": "1000 AA"
    },
    "email": "jane.doe@example.com",
    "language": "en-gb",
    "name": {
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "telephone": "+31123456789"
  },
  "order_token": "sample-order-token",
  "payment": {
    "card": {
      "cardholder": "Jane Doe",
      "cvc": "123",
      "expiry_date": "2030-10",
      "number": "!CARD_NUMBER!"
    },
    "include_receipt": true,
    "method": "card",
    "timing": "pay_online_now"
  }
}
  • The card details displayed here are placeholders. Do not reuse the example card details in a real request.
  • For online card payments, provide the CVC by default. The API may require additional authentication or verification fields for the selected payment flow.
  • For accommodation payments made at the property, follow the cvc_required or amex_cvc_required value returned by /accommodations/details.

See the Accommodation payment models for more details.

Try it yourself

References

Tutorial - Search, look and book flow

Version 3.1