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

When you call the /accommodations/search or /accommodations/availability endpoints, the following request values are used to determine what deals are available on 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 the response

The /accommodations/search or /accommodations/availability response contains details of any deals that are available on each returned product. The products.deal response object returns the following information:

discount_percentage - shows the total discount percentage that applies to the product's public_price, after all qualifying deals have been applied.
public_price - shows the product's original price. This is the price to which the discount_percentage is applied. Note: The product's book price (price.book) is the public_price minus the discount_percentage.
tags - identifies the type(s) of deal that have been applied to the product.

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

The following example shows a product that has deals available for booking on a mobile device, and for booking during a specific period. The total value of the discount on these deals is 28%. This discount is applied to the product's original price of €100, giving a discounted book 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 about the available deals for a product, but does not provide a complete breakdown.

In some cases, it might not be obvious from the data returned exactly how the discount_percentage value has been calculated. For example, if multiple deals apply, discounts may be applied sequentially. Alternatively, in cases where deals cannot be combined, the highest available discount would 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.

Important

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.

For example, suppose a call to /accommodations/search returned 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 show that information on the search results page like this.

Limited Time Deal Search

Similarly, if you received the same information from a call to /accommodations/availability, you could show that information on the property page like this.

Limited Time Deal Availability