# Promotions Message

## Overview

The Promotions message defines rules for discounting rates using
`OTA_HotelRateAmountNotifRQ`. For each rate, the defined promotions
are evaluated and the greatest allowed discount is applied to the
rate. This message type is optional and you only need to define
promotions if they are used in your system to apply rate discounts.

You can combine promotions and apply them to different user attributes,
such as device types (mobile, tablet, desktop) and country codes.

> [!IMPORTANT]
> **Key Point:** When multiple promotions apply to specific product rates (room type + rate plan + occupancy), the user receives the cheapest allowed promotion or combination of promotions, and the discounts are automatically applied.

For examples of various promotion-related scenarios, see
[How-tos](https://developers.google.com/hotels/hotel-prices/dev-guide/ari-promotions-message#promotionshowtos).

The following sections cover general guidelines, a basic example, and how-to
scenarios to get you started with adding and updating promotions.

## Guidelines

This section covers the common guidelines and special instructions for setting
promotions.

Use the following guidelines for promotions:

### Actions

Delete
:   Use a `delete` action in the `<Promotion>` element to delete a single
    promotion by its ID.

Overlay
:   Use an `overlay` action in the `<HotelPromotions>` element to replace
    all of the promotions for a property.

Delta
:   If no action is specified, then all of the promotions specified
    within `<HotelPromotions>` are added or replaced. If a promotion with that ID
    had never been added or had been deleted, then the promotion is added. If a
    promotion with that ID exists, it is overwritten with the new definition.

### General

- There can be a single or set of promotions for each property and each
  promotion has a set of conditions. That promotion can only be applied if the
  conditions are satisfied.

- Promotions apply to the rate for the itinerary. It is not possible to set a
  maximum discount per occupant.

- If you want a promotion to only apply to a specific date, room type, or rate
  plan, then specify that in the conditions for that promotion. If the
  promotion doesn't apply to a specific date, room type, or rate plan, then
  those don't have to be set.

- Each promotion is tied to a specific property. If you use the same promotion
  for multiple properties, you must send it separately for each property. To
  specify your property identifier, use the `hotel_id` attribute of the
  `<HotelPromotions>` element.

- You can include up to 99 promotions. Contact your Google TAM if you need to
  include more than this.

- Use the `<Stacking>` element to specify how promotions can be combined. By
  default, Google uses the `base` stacking type, meaning that the best eligible
  base promotion is selected and applied first, before other promotions. Note
  that `base` can only be combined with `second` or `any`, and can't be combined
  with another `base` or `none`.

- Even if there's a stack of several promotions that can be applied together,
  that stack might not actually be the one that's used if there is another
  single promotion or stack of promotions that offers the deeper discount. The
  promotion (combination) with the biggest discount is applied to the booking
  when multiple (combinations of) promotions are eligible.

- Send a Promotions message update whenever any changes occur that affect
  your promotions.

  > [!IMPORTANT]
  > **Key Point:** There is a limit of 500 promotions per property. You can use the `<Promotions>` message to remove promotions from a property.

### Tax-related

The best promotion (or stack of promotions) is applied to the `AmountAfterTax`
amount. If only `AmountBeforeTax` is specified, then the promotions are
applied to `AmountBeforeTax`.

## Example

This section provides a basic example of a Promotions message using required
and optional elements. Once you've prepared your file, send it to Google through
a POST message to this endpoint:

    https://www.google.com/travel/hotels/uploads/promotions

To learn more about how to push/POST the message, see
[Pushing messages](https://developers.google.com/hotels/hotel-prices/dev-guide/ari-overview#pushing-messages).

> [!IMPORTANT]
> **Key Point:** Send Google an updated promotion message every time your promotions change.

For the `hotel_id` attribute of `<HotelPromotions>`, use the unique Hotel ID
you used within your system for identifying the property. This value must match
the Hotel ID specified using `<id>` in the [`<listing>`](https://developers.google.com/hotels/hotel-prices/xml-reference/hotel-list-feed#listing)
element in the Hotel List feed. Consistency with your system is critical for
ensuring that Google is correctly displaying your data.

`UserCountry` is for listing the user locations (countries) that are eligible
for the promotion. If specified, only users in the listed countries are
offered the discounted rate.

> [!NOTE]
> **Note:** Setting a country code is optional and if not specified, users in any country are offered the discounted rate.

This example shows how to set a 15% discount for an extended stay
for users in the United States and Italy:

    <?xml version="1.0" encoding="UTF-8"?>
    <Promotions partner="account_x"
                id="123_abc"
                timestamp="2022-05-30T16:20:00-04:00">
      <HotelPromotions hotel_id="Property_1">
        <Promotion id="1">
          <Discount percentage="15"/>
          <UserCountries>
            <Country code="US"/>
            <Country code="IT"/>
          </UserCountries>
        </Promotion>
      </HotelPromotions>
    </Promotions>

For more examples, see
[Promotions examples](https://developers.google.com/hotels/hotel-prices/xml-reference/ari-promotions#promotions-examples).

## How-tos

This section provides solutions to scenarios you might encounter while setting
promotions.

### Scenario 1: How to add a discount promotion for extended stay

#### Description

You want to provide discounted nights on certain days of an extended stay.

#### Solution

Use the `FreeNights` setting to customize the type of discount applied depending
on the number of stay nights.

#### Sample

This sample shows how to add a 20% discount for two nights for every 7 nights
stayed for the specified range of booking dates. For a 15-night itinerary, a
20% discount applies to a total of 4 nights.

    <?xml version="1.0" encoding="UTF-8"?>
    <Promotions partner="account_x"
                id="123"
                timestamp="2022-05-05T16:20:00-04:00">
      <HotelPromotions hotel_id="Property_1">
        <Promotion id="1">
          <BookingDates>
            <DateRange start="2022-02-01" end="2022-06-30"/>
          </BookingDates>
          <Discount>
            <FreeNights stay_nights="7"
                        discount_nights="2"
                        discount_percentage="20"
                        night_selection="cheapest"
                        repeats="true"/>
          </Discount>
        </Promotion>
      </HotelPromotions>
    </Promotions>

### Scenario 2: How to set device types

You set `devices` to specify the user devices that are eligible for the
promotion. If specified, only users on the listed devices are offered
the discounted rate.

> [!NOTE]
> **Note:** If not specified, users on any device are offered the discounted rate.

#### Description

You want to specify which type of user device is eligible for the promotion.

#### Solution

Set the device type to one or more of the following values: `desktop`, `tablet`,
or `mobile`.

#### Sample

The following sample shows how to specify a 25% discount for mobile and
tablet users:

    <?xml version="1.0" encoding="UTF-8"?>
    <Promotions partner="account_x"
                id="123"
                timestamp="2022-05-20T16:20:00-04:00">
      <HotelPromotions hotel_id="Property_1">
        <Promotion id="1">
          <Discount percentage="25"/>
            <Devices>
              <Device type="mobile"/>
              <Device type="tablet"/>
            </Devices>
        </Promotion>
      </HotelPromotions>
    </Promotions>

### Scenario 3: How to replace old with new promotions

#### Description

The current set of promotions for a property are outdated or incorrect and need
to be replaced with an entirely new set.

#### Solution

Use the `overlay` action to replace the promotions.

> [!NOTE]
> **Note:** Using `overlay` (rather than using individual `delete`) is the recommended way to overwrite all of the promotions for a property. Use the `delete` action if you want to delete only specific promotions for a property.

#### Sample

The following sample shows the original two discounts of 20% and
30% for the property.

    <?xml version="1.0" encoding="UTF-8"?>
    <Promotions partner="account_x"
                id="123"
                timestamp="2022-05-20T16:20:00-04:00">
      <HotelPromotions hotel_id="Property_1">
        <Promotion id="1">
          <BookingDates>
            <DateRange start="2022-06-01" end="2022-07-31"/>
          </BookingDates>
          <Discount percentage="20"/>
        </Promotion>
        <Promotion id="2">
          <BookingDates>
            <DateRange start="2022-08-01" end="2022-08-31"/>
          </BookingDates>
          <Discount percentage="30"/>
        </Promotion>
      </HotelPromotions>
    </Promotions>

And then this sample shows how to use `overlay` to replace the existing
two promotions with a single promotion of 15% discount for the property.

    <?xml version="1.0" encoding="UTF-8"?>
    <Promotions partner="account_x"
                id="123"
                timestamp="2022-05-25T16:20:00-04:00">
      <HotelPromotions hotel_id="Property_1" action="overlay">
        <Promotion id="1">
          <BookingDates>
            <DateRange start="2022-06-01" end="2022-07-31"/>
          </BookingDates>
          <Discount percentage="15"/>
        </Promotion>
      </HotelPromotions>
    </Promotions>

### Scenario 4: How to remove one or all promotions

#### Description

You want to remove one or all promotions (without replacement) because the
property has removed all of its promotions without setting new ones, or
you made an error and need to correct it.

#### Solution

Use the `delete` action if you want to delete only specific individual
promotions for a property, and use the `overlay` (not `delete`) action to remove
all of the existing promotions without replacement.

> [!NOTE]
> **Note:** Using `overlay` (rather than individual `delete` actions) is the recommended way to overwrite all of the promotions for a property.

For details on how to replace promotions using `overlay`, see
[Scenario 3](https://developers.google.com/hotels/hotel-prices/dev-guide/ari-promotions-message#scenario3).

#### Samples

The following sample shows how to delete only one promotion for a property:

    <?xml version="1.0" encoding="UTF-8"?>
    <Promotions partner="account_x"
                id="123"
                timestamp="2022-05-20T16:20:00-04:00">
      <HotelPromotions hotel_id="Property_1">
        <Promotion id="1" action="delete"/>
      </HotelPromotions>
    </Promotions>

This sample shows how to remove all promotions without replacement
for a property:

    <?xml version="1.0" encoding="UTF-8"?>
    <Promotions partner="account_x"
                id="123"
                timestamp="2022-05-20T16:20:00-04:00">
      <HotelPromotions hotel_id="Property_1" action="overlay"/>
    </Promotions>

### Scenario 5: How to stack promotions

Stacking specifies how promotions can be combined. If not specified, the `type`
is assumed to be `base`, meaning that the best eligible base promotion is
selected and applied first, before other promotions. When the `type` attribute
of `Stacking` is `any`, it can be combined with any other promotion.

> [!NOTE]
> **Note:** The promotion (combination) with the biggest discount is applied to the booking when multiple promotion combinations are eligible.

#### Description

You want the user to have an option of using multiple promotions at the same
time for the same property.

#### Solution

Use stacking to set multiple discounts per property. A stack can have at most
one `base` and one `second`, but an unlimited number of `any`; and `any` can
be combined with the other types except for `none`.

#### Sample

This sample shows how to stack `base`, `second`, and `any` Stacking types. For
a combined discount of 15%, 25%, 10%, a $100 price is a total of
$57.38 (100 × .85 × .75 × .9).

    <?xml version="1.0" encoding="UTF-8"?>
    <Promotions partner="account_x"
                id="123"
                timestamp="2022-05-20T16:20:00-04:00">
      <HotelPromotions hotel_id="Property_1">
        <Promotion id="1">
          <Discount percentage="15"/>
          <Stacking type="base"/>
        </Promotion>
        <Promotion id="2">
          <Discount percentage="25"/>
          <Stacking type="second"/>
        </Promotion>
        <Promotion id="3">
          <Discount percentage="10"/>
          <Stacking type="any"/>
        </Promotion>
        <Promotion id="4">
          <Discount percentage="40"/>
          <Stacking type="none"/>
        </Promotion>
      </HotelPromotions>
    </Promotions>

Note that the combined discount for the stacking promotions 1 through 3 is
better than the discount for promotion 4. Promotion 4 can't be combined with
other promotions due to its stacking type (`none`). If promotion 4 had a
discount of 43% or higher, it would be used instead of the combination of
promotions 1 through 3.