Changes in V3

This section outlines the key architectural, design, and functional changes between Versions 2 and 3 of the Demand API. It is intended to assist with planning your migration from V2 to V3.

API architecture and design

This is the overall evolution in endpoints

From v2 to v3.0

In V2, the API employed a monolithic design tailored specifically for the accommodation vertical of the travel industry.

V3 introduces a modular architecture that:

Version 3.0

V3.0 introduces two new sets of endpoints:

✅ /accommodations/ endpoints - which focus on the accommodation vertical within the travel market.

✅ /common/* endpoints - which provide generic, cross-vertical information about locations (such as countries, cities, landmarks, and airports), payments (currencies and payment methods), and languages.

Version 3.1

V3.1 includes:

✅ /orders/ endpoints:

• which support common order processing and management functionality across verticals.

• These endpoints extend the API's capabilities to include Search, look and book and Post-booking integration types.

✅ This version also includes the possibility of using other verticals.

• Including the car rentals endpoints collection.

Authentication

In V3, each call to a Demand API endpoint must identify an API user that is authorised to access that endpoint.

Enable API user

An API user is a unique pairing of your partner id and one of your affiliate ids.

To enable an API user to access the Demand API, you must do the following:

Endpoint structure

The following table compares the structure of V2 and V3 endpoints.

Accommodation search example

See the differences in a simple search call on accommodation endpoint:

V2

GET https://distribution-xml.booking.com/2.10/hotelAvailability?
     city_ids=-2140479
     &guest_country="nl"
     &room1="A,A"
     &checkin="2023-08-15"
     &checkout="2023-08-16"

V3

POST https://demandapi.booking.com/3.1/accommodations/search
{
  "city": -2140479,
  "booker": {
      "platform": "desktop",
      "country": "nl"
      },
  "checkin": "2025-11-15",
  "checkout": "2025-11-18",
  "guests": {
      "number_of_rooms": 1,
      "number_of_adults": 2
      }
}

Reservation ids and order ids

An accommodation booking created in V2 is uniquely identified by a reservation_id, which is returned in the processBooking response. For example:

{
  "result": {
    "reservation_id": "1234567890"
    ...

An accommodation booking created in V3 has two identifiers, returned in the /orders/create response:

For example:

{
  ...
  {
    "accommodation": {
      "order": "509430129718799",
      "reservation": 2444627607
      ...

Error handling

The Error handling guide describes what errors can occur when calling V3 endpoints and what you should do to avoid or fix them.

You should update your error handling code in line with the guidance and information given there.

Also, note that V3 reports errors differently to V2:

• The endpoint now returns an HTTP error status code (4_xx_ for a client-side error or 5_xx_ for a server-side error).

• A response body is only returned with an HTTP 400 code, or with some 5_xx_ codes.

• The response body contains further details about the error, but uses a different structure to V2 - see Client error ids for more details. For example:

{
    "request_id": "01gw5aaj8dkh7fvgwa7phs916x",
    "errors": [
        {
            "id": "missing_parameter",
            "message": "Parameter 'checkin' is missing."
        }
    ]
}

• request_id is the unique identifier for the response. This replaces the errors.ruid identifier used in a V2 error response.

Common endpoints

New commond endpoints have been included so can be used acrosss verticals.

New location endpoints

The following new location endpoints are available in V3:

Example of airports response

{
    "data": [
        ...
        {
            "id": "CDG",
            "name": {
                "fallback": "Paris - Charles de Gaulle Airport",
                "en-gb": "Paris - Charles de Gaulle Airport"
            }
        },
        ...
    ]
}

Example of landmark response

{
    "data": [
        ...
        {
            "id": 1,
            "name": {
                "fallback": "station-amsterdam-centraal",
                "en-gb": "Amsterdam Central Station"
            },
            "coordinates": {
                "latitude": 52.378281,
                "longitude": 4.900070
            }
        },
        ...
    ]
}

New languages endpoint

The /common/languages endpoint returns a list containing the language code (id) and name of every language for which translations are available from the Demand API.

In V2, these language codes were only available in the documentation, not from the API itself.

For example:

{
   "data": [
       {
           "id": "ar",
           "name": "العربية"
       },
       ...
       {
           "id": "en-gb",
           "name": "English (UK)"

       },
       ...
       {
           "id": "zh-cn",
           "name": "简体中文"
       },
    ]
}

You can use these language codes with any endpoint that provides translatable data in its response:

• In the request, specify the language(s) you want to return.

• In the response, identify the language used in any translated string.

Multiple language support

In V2, you could only get response data from the hotels endpoint in a single language (using the language query parameter).

In V3, you can now get response data from the equivalent /accommodations/details endpoint in multiple languages in the same call. If your application supports several different languages, using V3 can result in a significant reduction in the number of calls you need to make to obtain your content.

V3 uses a new languages request field, in which you can specify an array of language codes. For example, to get response data in British English, Spanish, Arabic and Chinese, specify the following in the request:

{
    "languages": [
        "en-gb",
        "es",
        "ar",
        "zh-cn"
    ]
}

In the response, each translatable field will be returned in each of the requested languages for which a translation exists. For example:

"name": {
    "ar": "كوخ حديقة \n\n",
    "zh-cn": "花园小屋 ",
    "en-gb": "Garden Cottage",
    "es": "Casa de campo Garden"
},

The following V2 endpoints also use the language parameter, but their V3 equivalents do not use the languages request field:

• blockAvailability and hotelAvailability - The V3 equivalents of these endpoints (accommodations/availability and accommodations/search) do not return any translatable content, so do not provide the languages request field.

• reviews and reviewScores - These endpoints use the language parameter differently.

Affiliate ID tracking

To allow you to redirect a traveller from your application to Booking.com to complete a booking, several Demand API endpoints return URLs to specific Booking.com accommodation pages.

For reporting and attribution purposes, these URLs should include the affiliate id that the request is to be tracked against:

• In V2, you could specify the affiliate ID to be used in the affiliate_id request parameter. This parameter is not supported in V3.

• In V3, these URLs automatically include the affiliate id specified in the X-Affiliate-Id header in the request.

  • This makes it easier for partners who have multiple affiliate ids to track redirections on the affiliate, rather than partner, level.

  See the Authentication guide for more details

You should modify your code as required to use the new mechanism.

Redirect to book URL

In the table below:

• The V2 endpoints that return response fields containing redirection URLs, and the names of the returned fields.

  • If the affiliate_id request parameter was specified, these fields will contain a query parameter containing that affiliate_id value.

• The equivalent V3 endpoints that return response fields containing redirection URLs, and the names of the returned fields.

  • These fields will contain a query parameter containing the value of the affiliate id used to make the request.

The affiliate ID is appended to each redirection URL in the aid query parameter. For example:

{
   ...
   "deep_link_url": "booking://hotel/10004?affiliate_id=956509",
   ...
   "url": "https://www.booking.com/property/nl/testHotel-1.html?aid=956509",
   ...
}

Other improvements

• Pagination - V3 offers an easier way to use mechanism for paginating results.

• Support for long stays -Searches can now return data for long-stay bookings.

  • In an /accommodations/search request, the checkout date can now be up to 90 days after the checkin date.
  • In a V2 hotelAvailability request, the checkout date has to be within 30 days of the checkin date.

• Improved experience for more complex room needs, such as group and family searches.

Choose your migration guide