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.

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.

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.

• 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.

  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.

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> 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: 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.

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: 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: 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: 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.

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: 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.