ACCOMMODATION
/
Quick guide
Last updated

Accommodation quick guide

Follow this quick guide to start playing with our Accommodation API collection in your client application.

This quick guide shows the minimum steps needed to integrate the Demand API accommodation endpoints.

⏱️ Estimated time to complete: 10 - 15 minutes

Before you start

Before testing, make sure you have:

Checklist
☑Registered as a Booking.com Managed Affiliate Partner.
☑Access to Partner Centre (provided by your Booking.com Account Manager after signing the agreed contract).

☑

In Partner Centre, generated:

☑Have this Developer Portal open to access the Try-out console (see instructions below).

Steps

Follow these steps to test a basic example:

A traveller searches for a 2-night stay in Amsterdam for 2 adults in 1 room.

1. Search for accommodation

To find properties that match the use case search criteria:

→ Use the accommodations/search endpoint.

Example request:

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

See the accommodation search guide for examples and tips on creating search requests.

Example response:

The response contains a list of accommodations that match the specified search criteria, including the price and url to Booking.com property page.

In this example, the Demand API sandbox Onion hotel.

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

Keep the accommodation id for the next step.

→ Try it yourself

2. Get accommodation details

→ Call /accommodations/details using the accommodation id from the search response (10507360).

Example request:

{
  "accommodations": [
      10507360
  ],
  "extras": [
    "description"
  ],
  "languages": [
    "en-gb"
  ]
}
More details

Multiple languages can be requested; if data isn’t available in your preferred language, English is returned by default.

genius-bulb Use the extras field to retrieve more details about the accommodation. For example:

  • If you want to use a photograph in your search results, add the field "extras": ["photos"] to your request.
  • If you wish to see the property supported payment methods, add the field "extras": ["payment"] to your request.

Example:

  "extras": [
    "description",
    "photos",
    "facilities",
    "payment"
  ],

→ Try it yourself

Example response:

The response contains all the information about the selected accommodation including contact information, number of rooms, score/reviews, etc.

{
  "request_id": "01k2kv6g4de00n4cw4cvr4v5bm",
  "data": [
    {
      "id": 10507360,
      "name": {
        "en-gb": "Demand API Sandbox Hotel Orion"
      },
      "accommodation_type": 204,
      "booker_address_required": false,
      "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"
        },
        "reservations": null
      },
      "currency": "EUR",
      "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,
      "ranking": 4703915,
      "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=956509"
    }
  ]
}

3. Get availability and prices

→ Use the accommodations/availability endpoint with the same traveller criteria.

Example request:


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

Example response:

The response includes the available products and prices, together with a recommendation.

{
  "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": "2025-10-29T22:59:59+00:00",
            "schedule": [
              {
                "from": "now",
                "price": 0
              },
              {
                "from": "2025-10-29T23: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=2025-11-06&checkout=2025-11-08&no_rooms=1&group_adults=2"
  }
}

genius-bulb Highlight the recommendation field to show the best-priced option.

Prices can change between search and availability calls — always confirm before booking.

→ (Try it yourself)

4. Handle the booking

Choose your integration type:

  • Search and look → Redirect to the url in the availability response.

  • Search, look and book → Book within your application:

    1. Use /orders/preview to confirm price, policies, and payment options.
    2. Use /orders/create to complete the booking within your application.

For Search, look and book, you must have:

  • An approved business case.
  • A signed partner agreement.

Best practices

  • Always include your API key token and X-Affiliate-Id in every request.
  • Use the correct two-letter country code in lowercase.
  • Cache static location data (cities, countries, etc) to reduce API calls.

Next steps

Previous page
Next page