Rate Message

Overview

The Rate message (OTA_HotelRateAmountNotifRQ) defines the nightly occupancy rates for each room type and rate plan combination for specific date ranges. As part of the Rate message, Google supports occupancy-based pricing, enabling different nightly rates to be specified based on the maximum number of intended occupants.

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

Matching rate behavior

As users request specific occupancies, the rate they see depends on how you define prices in your Rate message. This section covers how these user requests are matched to your rates depending on the occupancy of their request, and the rates you define.

Key principles

A rate defined for a specific occupancy applies to all lesser occupancies, unless otherwise defined.
Requests for occupancies above those defined are considered not possible.
The occupancy-based pricing applies to both per-date pricing and LOS-based pricing models described below. This means you can specify rates for each occupancy. If a rate for a specific occupancy doesn't exist, the rate for the next highest occupancy is used. You may also define charges for additional guests and children using AdditionalGuestAmounts or ExtraGuestCharges which is applied up to the capacity defined for a room.

Key Point: There is a limit of 100 extra guest charges per property. You can use ExtraGuestCharge message to remove additional guest charges.

Benefits and examples

Efficiency

For multiple occupancies with the same rate amount, you don't need to set a rate for each occupancy. You can simplify your messages by setting only the highest occupancy value that is supported by the room type and rate plan. Users will see that rate for every occupancy less than or equal to your set value.

Example: The rates for a room type and rate plan are the same for occupancies one through four. Use the Rate message to set one rate for max occupancy of 4. Users searching for single, double, and triple occupancy will see that same rate. Users searching for 5 and above will not see rates.

Control

Distinct rates for alternative occupancies can be provided explicitly. Send a different rate for each occupancy value if you want more control over how Google matches requests to occupancy rates.

Example: If rates are defined for occupancies 3 and 1, single occupancy searches will display the singles rate, a double occupancy search will show the triple occupancy rate, and users searching for 4 and above will not see rates.

For more examples of various rate-related scenarios, see How-tos.

Required and optional elements

The XML Reference provides descriptions of the required and optional elements. For details on attributes and child elements, see Rate Elements & Attributes.

Syntax and schemas

Use the Rate Syntax example as a reference when you create the Rate message to ensure you're following the correct format.

You can use a third-party XML tool such as xmllint to validate your feeds with the published schemas before submitting them to Google. For the Rate message schema, see Hotel Ads schemas.

Pricing models

Per-date pricing

This is the standard pricing model used for most properties. The per-date pricing model is based on setting rates which are summed up across stay dates to arrive at a total price. In this model, all rates under a Rate element are interpreted as applying to a range of stay dates specified in <StatusApplicationControl>.

LOS-based pricing

The LOS-based (length-of-stay) pricing model is based on rates set for an arrival date and length of stay combination. Rates specified under the LOS-based pricing model are per-day. For example, if you send a rate of $100 for a length of stay of 3, the total price is calculated as 3x$100=$300.

You can make use of the LOS-based pricing model by specifying RatePlanType="26" on StatusApplicationControl elements. You also need to set RateTimeUnit and UnitMultiplier attributes on Rate elements in your XML. This causes all rates under the given Rate element to apply to stays defined by the arrival dates specified in <StatusApplicationControl> and the LOS value specified for UnitMultiplier.

You can make use of both per-date and LOS-based pricing models under a single account, however, each property should only use a single pricing model. Keep the following points in mind when implementing LOS-based pricing:

Rates for different lengths of stay are not combined when using LOS-based pricing. For example, an LOS rate of 3 does not get combined with an LOS of 1 in order to price an LOS rate of 4. The LOS rate of 4 must be explicitly specified.
The 1-night rate in LOS-based pricing is not used as an individual night rate in per-date pricing.
Each property should only use either LOS-based pricing or per-date pricing, depending on how rates are represented in your system.

To enable LOS-based pricing on your account, make the request through your TAM or contact us.

Guidelines or Actions

Per-date pricing

Delta: Add or update the per-occupancy rates for only the specified combinations of room type, rate plan, and stay dates specified in <StatusApplicationControl>.

Rate updates use the Delta action by default.
A Delta update does not alter any previously stored rates for other occupancies. For example, if you have specified rates for single and double occupancy rooms, and send a Delta rate update for the single occupancy room, the double occupancy rate remains unchanged.

Overlay: Delete all of the existing per-occupancy rates for the room type, rate plan, and dates specified in <StatusApplicationControl> and replace them with new rates. For example, if you have specified rates for single and double occupancy rooms, and you send an Overlay update for single occupancy room, Google will remove all previous rates (both single and double occupancies) and only the single occupancy rate will remain after the update.

Remove: Delete all of the existing per-occupancy rates for the room type, rate plan, and dates specified in <StatusApplicationControl>.

LOS-based pricing

Delta: Add or update rates per LOS value for only the specified combinations of room type, rate plan, and check-in dates specified in <StatusApplicationControl>. Replaces all the per-occupancy rates associated with the updated LOS values.

Rate updates use the Delta action by default.
A Delta update does not alter any previously stored rates for other lengths of stay. For example, if you have specified rates for LOS 1 and 2, and send a Delta rate update for LOS 1, then LOS 2's per-occupancy rates remain unchanged.
A Delta update overwrites all previously stored per-occupancy rates for the given length of stay. For example, if you have specified single and double occupancy rates for LOS 1, and send a Delta rate update for LOS 1 with only a single occupancy rate, the double occupancy rate is removed.

Overlay: Delete all of the existing per-occupancy rates for the LOS, room type, rate plan, and check-in dates specified in <StatusApplicationControl> and replace them with new rates. For example, if you have specified rates for LOS 1 and 2, and you send an Overlay update for LOS 1, Google will remove all previous rates (both LOS 1 and 2) and only the LOS 1 rate will remain after the update.

Remove: Delete all of the existing per-occupancy rates for all LOS of the room type, rate plan, and check-in dates specified in <StatusApplicationControl>.

Tax-related

If taxes and fees are simple, the total amount can be specified using AmountAfterTax. Complex taxes, such as for taxes and fees that apply per stay (rather than per night) can't be represented in AmountAfterTax.

In general, Google recommends using TaxFeeInfo rather than AmountAfterTax.

If possible, you should include AmountBeforeTax (even if you specify AmountAfterTax) since certain locales (for example, US) display the pre-tax price by default.

All taxes and fees that a user must pay (VAT, stay tax, cleaning fees, city tax, etc.) should be included, even if it's not paid at booking time, or not paid directly to the property.

Example

This section provides a basic example of a Rate message using required and optional elements. After you prepare your file, you must send it to Google using a POST message to the following endpoint: https://www.google.com/travel/hotels/uploads/property_data

To learn more about how to push/POST the message, see Pushing messages.

For HotelCode, 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. For <PackageID> and <RoomID>, use the same IDs you use within your system for rate plans and room types (respectively). Consistency with your system is critical for ensuring that Google is correctly displaying your prices and data.

This example shows how to set rates using a Delta action:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                            EchoToken="12345678"
                            TimeStamp="2022-02-25T20:50:37-05:00"
                            Version="3.0"
                            NotifType="Delta">
  <POS><Source><RequestorID ID="partner_key" /></Source></POS>
  <RateAmountMessages HotelCode="HotelID">
    <RateAmountMessage>
      <StatusApplicationControl Start="2022-12-01"
                                End="2022-12-31"
                                InvTypeCode="RoomID"
                                RatePlanCode="PackageID" />
      <Rates>
        <Rate>
          <BaseByGuestAmts>
            <BaseByGuestAmt NumberOfGuests="1" CurrencyCode="USD" AmountBeforeTax="XXX.XX" />
            <BaseByGuestAmt NumberOfGuests="2" CurrencyCode="USD" AmountBeforeTax="XXX.XX" />
            <BaseByGuestAmt NumberOfGuests="3" CurrencyCode="USD" AmountBeforeTax="XXX.XX" />
            <BaseByGuestAmt NumberOfGuests="4" CurrencyCode="USD" AmountBeforeTax="XXX.XX" />
          </BaseByGuestAmts>
        </Rate>
      </Rates>
    </RateAmountMessage>
</OTA_HotelRateAmountNotifRQ>

How-tos

This section provides solutions to scenarios you might encounter while sending Rate messages.

For examples of how to add, remove, and update rates, see Rate Examples.

Scenario 1: How to change per-occupancy pricing

Description

Nightly rates were previously defined for only double occupancy (which also applies to single occupancy), but now there is a cheaper rate for single occupancy.

Solution

Send the new occupancy 1 rate using the default Delta scoped update. This new value doesn't affect the occupancy 2 rate.

Scenario 2: How to replace per-occupancy rates for a property

Description

You previously defined rates for occupancies 1 through 4, but now only occupancies 1 and 2 are valid.

Solution

Use NotifType="Overlay" to replace all occupancy rates for a given property, room type, rate plan, and date(s). In this scenario, the Overlay action would list rates for occupancies 1 and 2.

Scenario 3: How to set the same rate for multiple occupancies

Description

A rate for a certain occupancy can be sold to a group with fewer people. In this scenario, you can simplify your messages by sending only the rate update for the max occupancy applicable.

Solution

If you have the same price for multiple occupancies, set the highest occupancy value that is supported by the room type and rate plan, and it automatically uses that value for lower occupancies. That is, no need to repeat the same nightly rate for occupancies 1-6 if they're all the same; just set it for 6.