# Accommodation tutorial

**Follow this end to end tutorial to learn how to use our [/accommodation endpoints](/demand/docs/open-api/demand-api/accommodations) 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](/demand/docs/open-api/demand-api/accommodations) in different integration flows, so you can integrate them with your client application

div
strong
⏱️ Estimated time to complete:
 30 - 45 minutes 
br
br
ul
li
strong
Purpose:
 Complete step-by-step scenario from search to booking with explanations.
li
strong
Who this is for:
 Managed Affiliated Partner that want to see how all endpoints connect in a real booking flow.
li
strong
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).
li
strong
Content:
ol
li
Search 
&
 Look flow
li
Search, Look 
&
 Book flow
li
strong
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](/demand/docs/development-guide/application-flows)):

* Search & look (redirect to Booking.com to make the booking)
* Search, look & book (create the order in your app by means of the [/orders](/demand/docs/open-api/demand-api/orders/) endpoints, requires approval).


## Before you start

Before you start, make sure you’ve completed the [prerequisites](/demand/docs/getting-started/try-out-the-api#before-you-start---prerequisites).
You’ll need:

✓ A [valid API key token](/demand/docs/development-guide/authentication/#api-key-management).
✓ Your `X-Affiliate-Id`
✓ Open the [try out console](/demand/docs/getting-started/try-out-the-api#try-out-console).
✓ Use the [sandbox environment](/demand/docs/getting-started/sandbox).

## 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](/demand/docs/development-guide/authentication/) section.

## Integration overview

You can implement one of two [integration types](/demand/docs/development-guide/application-flows):

* Search & look - You redirect the traveller to Booking.com to book.
* Search, look & book - You complete the booking in your app using the [/orders](/demand/docs/open-api/demand-api/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](/assets/try-out-1.738c4803e6742a9c2ccca92ba7428e7c80b43e0705c2abca8b9b69c7efbd42fb.4302f616.png)

## Steps - Search and look

details
summary
b
Step 1 - Search for matching accommodations
b
p
→ Use the [accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search) endpoint to find properties.

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


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

City and country lookup
* Use the location [cities](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities) and [countries](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries) endpoints to resolve the IDs and ISO‑2 codes.
* Country codes must be lowercase (e.g., nl).


→ [Try it yourself](/demand/docs/open-api/demand-api/accommodations/accommodations/search)

Response
The response contains a list of accommodations that match the specified search criteria. Example:


```json
{
  "id": 10507360,
  "currency": "EUR",
  "price": {
    "book": 184.00,
    "total": 184.00
  },
  "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=xxxxxx&checkin=2026-11-06&checkout=2026-11-08&no_rooms=1&group_adults=2&mcid=10"
}
```

For each accommodation in the list, the response contains:

* `id` -The accommodation’s unique identifier.
  * Keep this `id` to get further details about the accommodation in the next step.
* `price` - The best [available pricing](/demand/docs/accommodations/prices-accommodations) for the specified search criteria.
* `url`- It points to the relevant Booking.com search page.
  * The URL contains your affiliate id (aid) (in the example xxxxxx) so when redirecting travellers to the booking, it can be attributed to you.


See the [accommodation search guide](/demand/docs/accommodations/search-for-available-properties/) for more examples and tips.

details
summary
b
Step 2 - Get details of selected accommodations
b
p

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

→ Call [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) to get additional data about the properties returned in the previous search response.

Request
To get details about a specific accommodation:

1. Go to the [accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search) response.
2. Copy the returned accommodation’s unique identifier `id`.
3. Use it in your [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) request.
4. The returned response provides all the details about the selected accommodation.


Example:


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

> ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) 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](/demand/docs/open-api/demand-api/accommodations/accommodations/details)

Response
The response contains all the information about the selected accommodation including: contact information, number of rooms, reviews, supported policies, and products. Example:


```json
{
  "request_id": "01k2pmgg11mgkhjqfs9cje9anv",
  "data": [
    {
      "id": 10507360,
      "name": {
        "en-gb": "Demand API Sandbox Hotel Orion"
      },
      "accommodation_type": 204,
      "checkin_checkout_times": {
        "checkin_from": "12:00:00",
        "checkin_to": "20:00:00",
        "checkout_from": "08:00:00",
        "checkout_to": "12:00:00"
      },
      "contacts": {
        "general": {
          "email": "demand.api.dev@booking.com",
          "telephone": "+31207125609"
        },
      },
      "currency": "EUR",
      "deep_link_url": "booking://hotel/10507360?affiliate_id=956509",
      "fiscal_information": {
        "legal_name": "",
        "vat_number": ""
      },
      "is_genius": true,
      "is_work_friendly": false,
      "location": {
        "address": {
          "en-gb": "Oosterdoksstraat 154"
        },
        "city": -2140479,
        "coordinates": {
          "latitude": 52.376388,
          "longitude": 4.90919
        },
        "country": "nl",
        "districts": [
          145,
          9173
        ],
        "postal_code": "1011 DL",
        "regions": [
          1010
        ]
      },
      "meal_prices": {
        "breakfast": 12,
        "lunch": 10,
        "dinner": 15
      },
      "number_of_rooms": 300,
      },
      "rating": {
        "number_of_reviews": 0,
        "preferred": true,
        "review_score": null,
        "stars": 5,
        "stars_type": "official"
      },
      "spoken_languages": [
        "en-gb"
      ],
      "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=xxxxxx"
    }
  ]
}
```

Number of rooms
Note: The number of rooms is approximate count configured for this property, not the total number of rooms per property. See the [accommodations/details guide](/demand/docs/accommodations/look-accommodation-details) for more details.

details
summary
b
Step 3 - Display your search results page
b
p

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.*


details
summary
b
Step 4 - Get real-time availability and prices
b
p
→ Use the [accommodation's availability endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) using the same criteria as the search.

Request
To retrieve the availability and prices of a specific accommodation:

1. Go to the [accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search) response ([step 1](#step-1-search-for-matching-accommodations)).
2. And copy:
  * The returned accommodation `id`
  * The values used for `booker`, `checkin`, `checkout`, and `guests` in your search request.
3. Paste same values into your [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) request.



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

→ ([Try it yourself](/demand/docs/open-api/demand-api/accommodations/accommodations/availability))

Response
The response contains:

**Products** — List of available products (room + policies + price)

* The product is part of the accommodation offer, and includes a room, and associated policies for meals, cancellations, occupancy limits, applicable payment methods and timings, as well as any applicable deals and price.


**Recommendation** - The most affordable product matching the criteria, including allocation and number of guests.

> ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) Highlight the recommended product to the traveller as the best match.


Example:


```json
{
  "request_id": "01k2m3js8k6rkgb09vehxcfbjy",
  "data": {
    "id": 10507360,
    "currency": "EUR",
    "products": [
      {
        "id": "1050736003_405384551_0_42_0_1122794",
        "commission": {...},
        "deal": {
          "discount_percentage": 3,
          "public_price": 98.2,
          "tags": [
            "mobile_rate"
          ]
        },
        "maximum_occupancy": {
          "adults": 4,
          "children": null,
          "total": 4
        },
        "number_available_at_this_price": 6,
        "policies": {...},
        "price": {
          "book": 95.38,
          "total": 95.38
        },
        "room": 1050736003
      },
      {
        "id": "1050736003_377312697_0_41_0_1122794",
        "commission": {
          "amount": 0,
          "percentage": 0
        },
        "deal": {
          "discount_percentage": 5,
          "public_price": 140,
          "tags": [
            "mobile_rate"
          ]
        },
        "maximum_occupancy": {
          "adults": 4,
          "children": null,
          "total": 4
        },
        "number_available_at_this_price": 6,
        "policies": {
          "cancellation": {
            "free_cancellation_until": "2026-11-03T22:59:59+00:00",
            "schedule": [
              {
                "from": "now",
                "price": 0
              },
              {
                "from": "2026-11-03T23:00:00+00:00",
                "price": 31.5
              }
            ],
            "type": "free_cancellation"
          },
          "meal_plan": {
            "meals": [
              "breakfast"
            ],
            "plan": "breakfast_included"
          },
          "payment": {
            "prepayment_required": false,
            "timings": [
              "pay_at_the_property",
              "pay_online_later",
              "pay_online_now"
            ]
          }
        },
        "price": {
          "book": 133,
          "total": 133
        },
        "room": 1050736003
      },
    ],
    "recommendation": {
      "price": {
        "book": 95.38,
        "total": 95.38
      },
      "products": [
        {
          "id": "1050736003_405384551_0_42_0_1122794",
          "children": [],
          "number_of_adults": 2,
          "price": {
            "book": 95.38,
            "total": 95.38
          }
        }
      ]
    },
    "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509&checkin=2026-11-06&checkout=2026-11-08&no_rooms=1&group_adults=2"
  }
}
```

Important
Availability can change very quickly. For example if a product matching the search criteria is sold in the time between the calls to [accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search) and [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability), the `recommendation` field will be `null`.
Always handle this state.

details
summary
b
Step 5 - Display the product in property page
b
p

    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](/demand/docs/development-guide/application-flows/):

### Redirect to Booking.com (Search, look and redirect integration)

If you are using a [Search and redirect integration](/demand/docs/development-guide/application-flows/#search-and-look), **you cannot process bookings directly**.

* Redirect the traveller to the `url` (web) or `deep_link_url` (app) from the [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) response.
* The `url` contains your affiliate id (`aid`), so that the booking can be attributed to you.


For example:


```json
...
   "url": "https://www.booking.com/<SELECTED_ACCOMMODATION>.html?aid=xxxxx&checkin=2026-11-06&checkout=2026-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](/demand/docs/open-api/demand-api/orders).

Important
Requires approval and partner agreement.

details
summary
b
Step 1 - Preview the order
p
→ Call [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) to confirm final details (what’s being booked, what will be paid, when/how, and cancellation terms).

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

1. Go to the [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/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.

1. Paste same values into your [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) request.
2. Go to the [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) response (in step 4)
3. 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`)

1. Paste all the previously copied values into your [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) request.


Your request body should look like this example.


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

→ [Try it yourself](/demand/docs/open-api/demand-api/orders/orders/preview)

Response
The orders/preview response contains the `general_policies` information about the order, including payment timings and methods, as well as `price` and `product` details:

##### General policies:

| 
| general_policies |  | In the example | References |
| `payment` | It shows when (timing) and how (methods) the traveller can pay for the order. | The traveller must `pay_online_now`, using any of the indicated payment `cards` (cards are shown by their `id`). | * Use the [List payment cards](/demand/docs/open-api/demand-api/commonpayments/common/payments/cards) to find card names.
* See the [payments section](/demand/docs/payments/overview) for detailed examples.

 |
| `price` | It 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.

 | See the [Accommodation pricing guide](/demand/docs/accommodations/prices-accommodations) for more details. |


Example of `general_policies.payment`:


```json
{
  ...
  "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`:


```json
{
  ...
  "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:

| 
| <div style="width:100px">accommodation.products</div> | <div></div> | In the example | References |
| `policies` | Details of the cancellation and meal plan policies. | This product does not include any meals or free cancellation period. In the event of cancellation, there is a fee of `180` EUR. | See the [cancellation policies](/demand/docs/orders-api/cancellation-policies) section for detailed examples. |
| `price` | Detailed breakdown of what the traveller needs to pay for the product, including a full breakdown of the charges. | In the example, the city tax (`22`) is levied on a `per_person_per_night` basis, at a rate of 1.00 EUR. | See the [Accommodation pricing guide](/demand/docs/accommodations/prices-accommodations) for more details. |


Example for `accommodation.products.policies`


```json
{
  ...
  "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"
          }
        }
      }
    ]
  },
  ...
}
```

Example for `accommodation.products.price`


```json
{
  ...
  "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
          }
        }
      }
    ]
  },
  ...
}
```

##### Order token

A `order_token` encapsulates the preview (copy this for the next step)


```json
{
  ...
  "accommodation": {
    "id": 10507360,
    ...
    "order_token": "eyJhbGciOiJIUzI1NiJ9.eyJ....<truncated for display in this example>...QytoS0yU"
  },
  ...
}
```

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

Attention
The `order_token` expires after 15 minutes. You must therefore call [/orders/create](/demand/docs/open-api/demand-api/orders/orders/create) within this time window.

details
summary
b
Step 2 - Display your order preview page
p
* 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](/demand/docs/open-api/demand-api/orders/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.*


details
summary
b
Step 3 - Create the order
p
→ Call [/orders/create](/demand/docs/open-api/demand-api/orders/orders/create) to process the payment and make the reservation with the accommodation.

Request
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](/demand/docs/open-api/demand-api/orders/orders/preview) response.
  * Pass this token to the [/orders/create](/demand/docs/open-api/demand-api/orders/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 (only for `pay_online_now` timing)
* `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.


```json
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_online_now"
    }
  }'
```

→ [Try it yourself](/demand/docs/open-api/demand-api/orders/orders/create)

Response
The response contains the following information about the order:

* `order`: Unique id number that identifies the order. Use it to [cancel the order](/demand/docs/open-api/demand-api/orders/orders/cancel) or to get information about it in further post-booking tasks.
* `receipt_url`: A link to the payment receipt for the order.



```json
{
  ...
  "accommodation": {
    "order": "xxxxxxxx",
    ...
  },
  "payment": {
    "receipt_url": "https://secure.booking.com/payment_receipt.html?bn=12345678&pincode=1234&lang=en"
  }
}
```

Curious to know more?
* Check the [Orders section](/demand/docs/orders-api/order-preview-create) for more tips on how to preview and create your order requests.
* Learn more about all [Payment methods](/demand/docs/payments/payments-methods#credit-cards).
* For examples and instructions on different payment flows, refer to [Payments quick guide](/demand/docs/payments/how-to).
* Refer to [Payments - Use cases](/demand/docs/payments/models/accommodation-payment-models) section for more details on how to set orders for different payment scenarios.