# 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`](https://developers.google.com/hotels/hotel-prices/xml-reference/ari-rate#additional-guest-examples) or [`ExtraGuestCharges`](https://developers.google.com/hotels/hotel-prices/xml-reference/ari-extra-guest-charges) which is applied up to the capacity defined for a room. > [!IMPORTANT] > **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. > [!IMPORTANT] > **Key Point:** For a given room and rate plan there can be a maximum of 50 occupancy rates per property. For more examples of various rate-related scenarios, see [How-tos](https://developers.google.com/hotels/hotel-prices/dev-guide/ari-rate-message#ratehowtos). ### Required and optional elements The [XML Reference](https://developers.google.com/hotels/hotel-prices/xml-reference/ari-overview) provides descriptions of the required and optional elements. For details on attributes and child elements, see [Rate Elements \& Attributes](https://developers.google.com/hotels/hotel-prices/xml-reference/ari-rate#property-data-elements). ### Syntax and schemas Use the [Rate Syntax](https://developers.google.com/hotels/hotel-prices/xml-reference/ari-rate#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](https://developers.google.com/hotels/hotel-prices/dev-guide/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 ``. ### 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 `` 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](https://support.google.com/hotelprices/gethelp). ## 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 ``. - 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 `` 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 ``. > [!IMPORTANT] > **Key Point:** For `Per-date` and `LOS-based` pricing models there is a limit of 5000 products for the room type and package combinations per property. You can use the `Overlay` and `Remove` notifications types to remove previously defined products. 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 ``. 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 `` 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 ``. 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](https://developers.google.com/hotels/hotel-prices/dev-guide/ari-overview#pushing-messages). > [!NOTE] > **Note:** Send Google a Rate message whenever any of your nightly rates change. 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 [`` in the `` element](https://developers.google.com/hotels/hotel-prices/xml-reference/hotel-list-feed#listing) in the Hotel List Feed. For `` and ``, 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: ## 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](https://developers.google.com/hotels/hotel-prices/xml-reference/ari-rate#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. > [!NOTE] > **Note:** The default occupancy value is 2 if `NumberOfGuests` is unset.