Retrieve deals, target and CUG rates

Learn how to provide traveller context to retrieve eligible accommodation deals and rates, and how to interpret the discount information in the response.

v3.2 v3.3

The deals and rates returned by the Demand API can depend on the traveller’s country, platform, stay dates, authentication status and your partner configuration.

This guide covers:

• Deals — Promotional discounts that may be tied to a campaign or time period.
• Target rates — Rates for eligible travellers, for example based on their platform or location.
• Closed user group (CUG) rates — Rates available to eligible travellers in a defined user group.

The request examples use the v3.3 request and response structure. For v3.2 integrations, use the version-specific API reference and deal-tag values. Bundles and inventory rates are covered in their own guides.

Use the accommodation search and availability flow to retrieve products for the requested stay and traveller context.

1. Call /accommodations/search with the traveller’s booker context, stay dates and guest details. Include products in the extras field to receive product information.
2. Call /accommodations/availability with the selected accommodation and the same applicable traveller context to retrieve current availability, prices and product details.
3. Before creating an order, call /orders/preview with the selected product and applicable accommodation details to validate the order and review its current price and terms.

The booker object describes the traveller context used to determine applicable prices and rates.

The checkin and checkout dates are top-level request fields; they are not part of the booker object.

Stay dates can affect eligibility for time-sensitive discounts.

To request rates for an authenticated traveller, include authenticated in booker.user_groups. Only include this value when the traveller is authenticated.

• Do not send membership-tier values such as genius or genius2 unless the schema and your partner-specific integration guidance explicitly support them.
• Whether an authenticated traveller receives a particular CUG rate depends on their eligibility and your partner configuration.

{
  "booker": {
    "country": "us",
    "platform": "desktop",
    "user_groups": [
      "authenticated",
      "genius2"
    ]
  },
  "checkin": "2026-12-05",
  "checkout": "2026-12-14",
  "city": -2140479,
  "extras": [
    "products"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

The following v3.3 request supplies a mobile platform and United States country context. It also includes the stay dates and guest details required for an accommodation search.

{
  "booker": {
    "country": "us",
    "platform": "mobile"
  },
  "checkin": "2026-12-05",
  "checkout": "2026-12-14",
  "city": -2140479,
  "extras": [
    "products"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

Use the traveller’s actual country and platform. Use the common/locations/countries endpoint to retrieve supported country codes.

When a product has discount information, its deal field can contain a discount percentage, the original price before discounts and tags describing the applied deals. The field can be null when no deal information applies.

Monetary values are returned as objects with accommodation_currency and booker_currency amounts. The traveller-facing display amount is returned in price.display.

The example below assumes there are no additional charges, so the display amount matches the discounted amount.

The following example shows an accommodation product with a 28% total discount.

Its public_price is 100.00, and its resulting price.display is 72.00. The returned tags indicate that the product includes a mobile rate and a limited-time deal.

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 10004,
      "products": [
        {
          "id": "1000420_95127794_2_0_0",
          "deal": {
            "discount_percentage": 28,
            "public_price": {
              "accommodation_currency": 100.00,
              "booker_currency": 100.00
            },
            "tags": [
              "mobile_rate",
              "limited_time_deal"
            ]
          },
          "price": {
            "display": {
              "accommodation_currency": 72.00,
              "booker_currency": 72.00
            },
            "total": {
              "accommodation_currency": 72.00,
              "booker_currency": 72.00
            }
          }
        }
      ]
    }
  ]
}

The deal.tags array identifies characteristics or categories associated with the discounts applied to the product.

• Do not use deal tags as identifiers for an underlying promotion or pricing configuration.
• Different discounts can share the same tag, and the tags do not expose the rules used to calculate the price.
• More than one tag can be returned for a product.

The following deal tags can be returned per version:

In version 3.3, deal tags provide more granular classifications for promotional campaigns.

The seasonal_deal tag is replaced by these tags:

A product can be eligible for more than one type of discount.

This request supplies the country, platform and authentication context used to determine eligibility.

{

  "booker": {
    "platform": "mobile",
    "country": "es",
    "user_groups": ["authenticated", "genius"]
  },
  "checkin": "2026-12-05",
  "checkout": "2026-12-14",
  "extras": ["products"],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }

}

The API returns applicable discounts according to the traveller’s eligibility, your partner configuration and any rate-stacking settings.

Use deal.discount_percentage to understand the total discount represented in the response. Do not calculate it by adding or interpreting the values in deal.tags.