Deals

Learn how to request, return and display information about deals

Booking.com offers different incentives to property owners to help them market their products - for example, seasonal deals such as Black Friday, or special rates for mobile users.

As a Demand API affiliate partner, you have access to specific incentives, allowing you to offer them to your customers. (If you need more information about the deals you can access, and any conditions on how to use them, contact your Account Manager).

In the Demand API, a deal is a discounted product price that is available to a traveller when one or more of these incentives apply.

How to request deal information

To access deal information, use the /accommodations/search or /accommodations/availability endpoints. The following parameters help determine the deals available for the returned products:

The API key used in the Authorization: Bearer header identifies the partner and affiliate IDs that you are using to make the request. Those IDs define what deals you have access to.
checkin and checkout: Include deals that are valid for the specified dates.
booker: Include deals that are only available if a traveller meets a specific condition. For example, they are logged in to your website or are using a mobile device.

For more details about how to return deal information, see the individual endpoint descriptions.

Example:

{
...
  "booker": {
    "platform": "mobile",
    "country": "us",
    "user_groups": ["authenticated"]
  },
  "checkin": "2023-09-01",
  "checkout": "2023-09-02",
  "extras": ["products"],
...
}

Deal information in responses

When you request deals via the /accommodations/search or /accommodations/availability endpoints, the products.deal object provides details about any available deals.

The response contains:

discount_percentage - The total discount percentage applied to the product's public_price after all qualifying deals are factored in.
public_price - The original price of the product, before discounts. This is the price to which the discount_percentage is applied.

The product's book price (price.book) is the public_price minus the discount_percentage.

tags - Identifies the types of deals applied to the product.

If no deals are available, products.deal returns null.

Example of response

The following example shows a product eligible for a 28% discount, applicable when booking via a mobile device or during a specific promotional period.

The original price is €100, resulting in a discounted price of €72.00.

{
  ...
  "currency": "EUR",
  ...
  "products": [
    ...
    "id": "xxxxxxxx_x_xxxxxxxxx_x_x_x",
    "deal": {
      "discount_percentage": 28,
      "public_price": 100.00,
      "tags": [
        "mobile_rate",
        "limited_time_deal"
      ]
    },
    ...
    "price": {
      "book": 72.00,
    },

Tags and discount_percentage

The products.deal object provides summary information on available deals for a product. However, it does not always give a detailed breakdown of how the discount_percentage is calculated.
If multiple deals apply, discounts may be applied sequentially.
Alternatively, if deals cannot be combined, only the highest available discount will be returned.

How to display deal information

You can use the information from the products.deal object to show that a deal is available on a product.

Displaying deals

If you display the discount_percentage you must display the public_price as well - typically as a strikethrough price.
You must only show available discounts to eligible travellers - for example, only show mobile_rate discounts to travellers who are using an appropriate mobile device.

Display example

For example, suppose a call to /accommodations/search returns the following deal information about a product:

{
  ...
  "currency": "EUR",
  ...
  "products": [
    ...
    "id": "xxxxxxxx_x_xxxxxxxxx_x_x_x",
    "deal": {
      "discount_percentage": 45,
      "public_price": 1005.00,
      "tags": [
        "limited_time_deal"
      ]
    },
    ...
    "price": {
      "book": 553.00,
    },

You could showcase this on the search results page as follows:

Limited Time Deal Search

Similarly, if you receive the same information from a call to /accommodations/availability, you can display it on the property page like this:

Limited Time Deal Availability