Demand API migration FAQs

Yes, partners may run v2 and v3 integrations in parallel during the transition phase (until 31st July 2025).

However, we recommend switching exclusively to v3 once your integration is complete. This ensures access to improved data structures and enhanced features.

• Migrate application flows.
• Migrate individual endpoints.

In v3, use products.price.book for equivalent pricing information.

• The "book" price is also known as "display price" and is the price shown to users in pre-booking stages.
• This price is tailored to comply with local regulations based on the booker.country.

Use the "book" price value when showing prices to travellers.

Theblock_id equivalent in v3 is the product.id from the products array in the /accommodations/availability response to identify room and rate combinations.

In v3 the equivalent is the products.price.book price:

• The "book" price is also known as the "display price" as this is the price you must show to users in pre-booking stages.
• It is tailored to comply with local regulations, and price modes—sometimes presenting a subtotal and excluding certain fees or taxes for clarity or compliance.
• The amount shown may include or exclude certain fees or taxes, depending on the country regulation (based on the booker.country value).
• For example, some jurisdictions require all mandatory charges to be included, while others allow some to be excluded.

Example in /accommodations/search response with book price:

{
  "products": [{
      "id": "1050736002_377311511_0_2_0",
      "price": {
        "book": 184.00,
        "total": 184.00
      },
      "room": 1050736002
  }]
}

In v3, refundability is expressed under the cancellation_policy object:

• Located in /accommodations/availability response under policies.cancellation.
• The presence of a free_cancellation_until timestamp indicates a refundable rate.

If the object has no free cancellation window or penalties apply from the start, the rate is considered non-refundable.

In v3.1, multi-room bookings are supported via the /orders/create endpoint using an array of rooms objects, each with a corresponding product_id, guest_info, and rate selection.

This enables submitting all rooms in one booking flow.

No. Demand API v3 does not include a region_type field.

In v3.1 there is an equivalent which is prepayment_required

• You can find it in the accommodation/availability response, under policies.payment.payment_required
• It indicates whether prepayment is required for the block.

This is equivalent to the deposit_required field in V2.

Bunk bed is identified as Bed_type_id=4, name=bunk bed in Demand API.

• In both v2 and v3 (or above) a bunk bed refers to single beds that are stacked vertically.
• Booking.com assumes that “1 bunk bed” accommodates 1 guest.

This field has been renamed to logged_in_deal in v3.

For travellers to have access to this sort of deals, they must be authenticated.

You can find the equivalent information in v3 by calling the orders/details endpoint, passing the extras:payment parameter in the request, and looking at data[].payment object.

Example:

      "payment": {
        "accommodations": {
          "authorization_form": "https://secure-admin.booking.com/airplus_auth_form_pdf.html?token=anNvbl9saHI0XzM1NzVmZDc1LTM2NTItNDQwZi1hZTk0LWM5ZTdmMzQzMzc1Yg%3D%3D&lang=en-us",
          "receipt_url": null,
          "reservation": 4836876659
        },
        "method": "card",
        "paid": null,
        "pending": null,
        "timing": "pay_at_the_property"
      },

Yes, use the orders/modify endpoint to:

• Update credit card details.
• Change checkin and checkout dates.
• Edit guest info and preferences (such as guest allocation, guest names, and smoking preferences)

Yes, v3 supports v2-originated bookings.

Use the v3 dedicated endpoints including the desired v2 reservation id in the request:

• orders/cancel
• orders/modify

The /orders/details endpoint returns information at the order level, which may include multiple travelling services (e.g. accommodation, flights, cars, etc) - Use it for a high-level overview of the entire order.

In contrast, /orders/details/accommodations provides product-level details specifically for accommodation bookings - Use this when you only need property-related data.

For other travel services, Demand API v3.1 included:

• /orders/details/cars - gives detailed information about the car rental component of the order - Use this if the order includes car hire services.
• /orders/details/flights - returns details for the flight portion of the order, where applicable - Use this when flight data is required.

Version 3 supports a broader range of rates than v2, including:

• Long-stay rates.
• Third-party inventory rates (commissionable and non-commissionable).

Yes, v3 supports loyalty and membership discounts. These are categorised as Closed User Group (CUG) rates and are often referred to as logged_in_deals.

To access these rates, users must be authenticated and meet specific eligibility criteria, such as Genius membership.

When making requests, you should include "authenticated" in the user_groups parameter, along with the specific membership tier (e.g., "genius2").

Example of a request body:

"booker": {
  "platform": "desk",
  "country": "us",
  "user_groups": [
      "authenticated",
      "genius2"]
  }

In the orders/details response, loyalty reward information is available under the loyalty_reward field.

In version 3, the inclusion of breakfast in a rate can be identified using the policies.meal_plan object and checking the sort of meal or plan included.

You can find the meal plan policy within the products.policies.meal_plan field in the response of the following endpoints:

• Pre-booking:
  • /accommodations/search
  • /accommodations/availability
  • /accommodations/bulk-availability
• Booking:
  • orders/preview
• Post-booking:
  • orders/details
  • orders/details/accommodations

For example, in case of including breakfast the orders/preview response would be:

{
    "products": [
      {
        "id": "1050736002_377311511_0_2_0",
        "policies": {
          "cancellation": [
            {
              "from": "now",
              "price": {
                "accommodation_currency": 180.00,
                "booker_currency": 180.00
              }
            }
          ],
          "meal_plan": {
            "meals": ["breakfast"],
            "plan": "breakfast_included"
          }
        }
      }
    ]
  },
  ...
}

Yes. Demand API v3 uses different pagination strategies:

No, you should not cache prices or availability data for a property, as this information can change frequently and rapidly. Using cached prices or availability data may cause a request to fail because the data is stale and invalid.

• Price and availability data is returned by the /accommodations/search and /accommodations/availability endpoints.
• However, you should always confirm final pricing and availability via orders/preview before creating a booking.

Yes, you can use the Test accommodation ID 10507360 - Demand API sandbox Hotel Orion in the sandbox environment to play with our accommodation endpoints.

For our Managed Affiliate partners, we recommend to use the Sandbox testing environment in this developer portal console.

• This is the "try it" option next to each endpoint specification within the API references section.

Yes, in v3.1, use payment.business_information.billing.vat in the /orders/create request.

This field is part of the business_information object, which also contains the company name, country, and billing email.

Here is an example of how it is structured in the /orders/create request:

"business_information": {
  "company": "Company Name",
  "billing": {
    "address": {
      "country": "nl"
    },
    "email": "your_company_email@example.com",
    "vat": "VALID VAT NUMBER"
  }
}

CVV suppression is not supported in V3.

However, there is a cvc_required field under the 'payment' object, in the /accommodations/details response.

This field indicates whether the CVV is required for the defined accommodation.

You can find the commission information in the commission object within the orders/details endpoint response. Example:

"commission": {
      "actual_amount": null,
      "actual_percentage": null,
      "estimated_amount": {
        "accommodation_currency": 17.5,
        "booker_currency": 19.23
      }
    }

Here's what you need to know about commission in v3 and v2 equivalents:

Important notes:

• Commission is not returned if it's not enabled for a partner or if an order is cancelled (in which case it will be returned as 0 or null).

• The actual_amount and actual_percentage fields are only populated once the guest has checked out of the property. You can then use the orders/details endpoint to check commissions.

  See the Orders details guide for examples and best practices.

• Payment instructions in v3, specifically the authorisation_form, can be found in the /accommodations/details response under payment.methods.cards.virtual_cards.
• The authorisation form is used for "pay at the property" bookings where Corporate Partners pay on behalf of their employees using Virtual Credit Cards (VCC). It helps the property understand how to charge the partner's VCC when the guest arrives.

When creating an order, the authorisation form URL can be passed in the /orders/create request body under payment.business_information.authorisation_form.

In v2.10, there were "payable" and "bookable" flags, however in v3 there are some equivalencies:

• Find the payable flag in the v3 accommodations/details endpoint(static data) - indicates the available methods for paying at the property timing.

• You can find the equivalent bookable flag information in the v3 orders/preview endpoint - indicates the available methods for paying online.