Promotions

If you have a backend that provides feeds for multiple accounts, this value needs to match the ID attribute value specified in the <RequestorID> element of your <OTA_HotelRateAmountNotifRQ> and <OTA_HotelAvailNotifRQ> messages for the same account.

Promotions for a property. Each promotion applies to a single property.

Unless <Stacking> is used, the promotion with the biggest discount is applied to the booking when multiple promotions are eligible.

If specified, the value must be "overlay". When the value is "overlay", all stored promotions are deleted prior to storing the promotions specified in the current message.

If not specified, then each promotion specified in the current message is either:

• Added (if none of the stored promotions has the same id)
• Updated (if a stored promotion has the same id)
• Deleted (if a stored promotion has the same id and the value of the action attribute for the promotion specified in the current message is "delete")

A single promotion for a property. Note that if action="overlay" and a <Promotion> is not specified, all promotions for the property are deleted.

If you need to use more than 99 promotions, contact your Technical Account Manager (TAM).

If specified, the value must be delete. If not specified and a promotion with the same id isn't stored, then this promotion is stored. Otherwise, if not specified and a promotion with the same id is stored, then the existing promotion is updated.

If delete is specified, the stored promotion with the same id is deleted. When using delete, don't include any child elements in <Promotion>. Also, delete is not allowed in conjunction with <HotelPromotions action="overlay"/>.

The starting date or datetime (based on the property's time zone), inclusive, of the range.

• The date or datetime specified by start must be earlier than (or the same as) the date or datetime specified by end.
• If start isn't specified, the range is effectively unlimited in terms of a start time.
• If start is populated as date "YYYY-MM-DD", it is interpreted as datetime "YYYY-MM-DDT00:00:00".

The ending date or datetime (based on the property's time zone), inclusive, of the range.

• The date or datetime specified by end must be later than (or the same as) the date or datetime specified by start.
• If end isn't specified, the range is effectively unlimited in terms of an end time.
• If end is provided as date "YYYY-MM-DD", it is interpreted as datetime "YYYY-MM-DDT23:59:59".

The days of the week that are allowed in the date range. If not specified, all days are allowed in the date range. Each character in the string specifies a day. For example, "MTWHF" specifies that weekdays are allowed in the date range.

Valid characters are:

• M for Monday
• T for Tuesday
• W for Wednesday
• H for Thursday
• F for Friday
• S for Saturday
• U for Sunday

Any character combination is valid.

Valid value types are:

• Integer: The number of days before the check-in date. For example, a value of 30 indicates the promotion only applies to bookings at least 30 days before the check-in date.
• ISO 8601 Duration (days, hours, and minutes): The number of days (and optionally hours/minutes) before the check-in date. For example, a value of P30D indicates the promotion only applies to bookings at least 30 days before the check-in date. A value of P30DT6H requires booking on or before 18:00 on the 30th day before arrival.

Valid value types are:

• Integer: The number of days before the check-in date. For example, a value of 30 indicates the promotion only applies to bookings at most 30 days before the check-in date.
• ISO 8601 Duration (days, hours, and minutes): The number of days (and optionally hours/minutes) before the check-in date. For example, a value of P30D indicates the promotion only applies to bookings at most 30 days before the check-in date. A value of P30DT6H requires booking on or after 18:00 on the 30th day before arrival.

Defines restrictions on the maximum value that a rate can be set to after promotions are applied.

Promotions must always specify a <Discount> or a <BestDailyDiscount>, so to create a promotion that only applies a <Ceiling>, one option is to set a <Discount> with a percentage of 0.

If stacking is configured, then multiple promotions with <Ceiling> could apply to a single stay. Each promotion would apply its discount, immediately followed by its ceiling. The following example demonstrates how each ceiling contributes to the next promotion calculation in the stack.

Example:

Pricing a 1-night stay where AmountBeforeTax is 100 and there is a stack of two promotions:

1. Promotion with stacking type base, a fixed_amount of 25, and a ceiling amount_per_night of 60
2. Promotion with stacking type second, fixed_amount of 25, and a ceiling amount_per_night of 90

Here is the order of calculation:

1. The base promotion is applied first and discounts the AmountBeforeTax to 75, but then the ceiling lowers it to 60.
2. The second promotion discounts the AmountBeforeTax from 60 to 35. This is below the ceiling of 90 so the second ceiling is not applied. The final rate is 35.

The fact that 60 is a stricter overall ceiling is irrelevant since it is valid only for its own promotion, and there can be no single ceiling that spans the entire promotion stack.

The maximum amount that a nightly rate can be set to after the discount is applied.

If a <Floor> element is also specified, this must be set to a value greater than or equal to the amount_per_night attribute in <Floor>.

amount_per_night is applied to taxes and fees when they are included in the nightly rate using AmountAfterTax, but not those specified using TaxFeeInfo.

Defines restrictions on the minimum value that a rate can be set to after promotions are applied.

Promotions must always specify a <Discount> or a <BestDailyDiscount>, so to create a promotion that only applies a <Floor>, one option is to set a <Discount> with a percentage of 0.

<Floor> logic still applies to <FreeNights> discounts, even if the free night has a 100% discount applied to it.

If stacking is configured, then multiple promotions with <Floor> could apply to a single stay. Each promotion would apply its discount, immediately followed by its floor. The following example demonstrates how each floor contributes to the next promotion calculation in the stack.

Example:

Pricing a 1-night stay where AmountBeforeTax is 100 and there is a stack of two promotions:

1. Promotion with stacking type base, a fixed_amount of 25, and a floor amount_per_night of 90
2. Promotion with stacking type second, fixed_amount of 25, and a floor amount_per_night of 60

Here is the order of calculation:

1. The base promotion is applied first and discounts the AmountBeforeTax to 75, but then the floor raises it up to 90.
2. The second promotion discounts the AmountBeforeTax from 90 to 65. This is above the floor of 60 so the second floor is not applied. The final rate is 65.

The fact that 90 is a stricter overall floor is irrelevant since it is valid only for its own promotion, and there can be no single floor that spans the entire promotion stack.

The minimum amount that a nightly rate can be set to after the discount is applied.

If a <Ceiling> element is also specified, this must be set to a value less than or equal to the amount_per_night attribute in <Ceiling>.

amount_per_night is applied to taxes and fees when they are included in the nightly rate using AmountAfterTax, but not those specified using TaxFeeInfo.

A date range specifying when check-in must occur for the promotion to be applied. This element is not required if you're deleting one or more promotions.

The YearlessDate format is also supported.

• If one of start or end is a yearless date, both must be populated as yearless dates.
• Yearless date ranges must not wrap around the new year. Instead, represent the range as two adjacent date ranges. For example, {"12-29", "01-05"} can be represented as {"12-29", "12-31"} and {"01-01", "01-05"}.

The days of the week that are allowed in the date range. If not specified, all days are allowed in the date range. Each character in the string specifies a day. For example, "MTWHF" specifies that weekdays are allowed in the date range.

Valid characters are:

• M for Monday
• T for Tuesday
• W for Wednesday
• H for Thursday
• F for Friday
• S for Saturday
• U for Sunday

Any character combination is valid.

A date range specifying when check-out must occur for the promotion to be applied. This element is not required if you're deleting one or more promotions.

The YearlessDate format is also supported.

• If one of start or end is a yearless date, both must be populated as yearless dates.
• Yearless date ranges must not wrap around the new year. Instead, represent the range as two adjacent date ranges. For example, {"12-29", "01-05"} can be represented as {"12-29", "12-31"} and {"01-01", "01-05"}.

The days of the week that are allowed in the date range. If not specified, all days are allowed in the date range. Each character in the string specifies a day. For example, "MTWHF" specifies that weekdays are allowed in the date range.

Valid characters are:

• M for Monday
• T for Tuesday
• W for Wednesday
• H for Thursday
• F for Friday
• S for Saturday
• U for Sunday

Any character combination is valid.

Exactly one of Discount or BestDailyDiscount must be specified.

Specifies the discount to be applied for this promotion.

Exactly one of percentage, fixed_amount, fixed_amount_per_night, fixed_price, or fixed_price_per_night is required.

A decimal value from 0-100 which specifies the percentage discount. It is applied to AmountAfterTax (or AmountBeforeTax if AmountAfterTax isn't specified).

Examples:

• If AmountAfterTax is 100 and percentage is 20, then

  promotion rate = AmountAfterTax * (1 - percentage discount)

  80.00 = 100 * (1 - 0.2)

• If AmountBeforeTax is 100, percentage is 20 and TaxFeeInfo specifies a tax of 10, then

  promotion rate = AmountBeforeTax * (1 - percentage discount) + tax

  90.00 = 100 * (1 - 0.2) + 10

Exactly one of percentage, fixed_amount, fixed_amount_per_night, fixed_price, or fixed_price_per_night is required.

A fixed amount to be subtracted from the sum of the AmountAfterTax nightly rates (or sum of AmountBeforeTax nightly rates if AmountAfterTax isn't specified). It is assumed to be in the same currency as nightly rates. If this is larger than the sum of nightly rates, the resulting value is zero.

Examples:

• If we're pricing a 1-night stay where AmountBeforeTax is 90, AmountAfterTax is 100, and fixed_amount is 20, then

  promotion rate = AmountAfterTax - fixed discount

  80.00 = 100 - 20

• If we're pricing a 1-night stay where AmountBeforeTax is 100, fixed_amount is 20, and TaxFeeInfo specifies a tax of 8%, then

  promotion rate = (AmountBeforeTax - fixed discount) * (1 + percentage tax)

  86.40 = (100 - 20) * 1.08

• If we're pricing a 1-night stay where AmountBeforeTax is 50, fixed_amount is 60, and TaxFeeInfo specifies a tax of 10, then

  promotion rate = (AmountBeforeTax - fixed discount) * tax

  10.00 = 0 + 10

• If we're pricing a 3-night stay where the AmountAfterTax values are 100, 110, and 120; and fixed_amount is 150, then

  promotion rate = sum(AmountAfterTax) - (fixed discount)

  180.00 = (100 + 110 + 120) - 150

Exactly one of percentage, fixed_amount, fixed_amount_per_night, fixed_price, or fixed_price_per_night is required.

A fixed discount applied to each of the AmountAfterTax nightly rates (or the cheapest N if applied_nights is specified). If AmountAfterTax isn't specified, it is applied to AmountBeforeTax. It is assumed to be in the same currency as nightly rates. If fixed_amount_per_night is larger than a nightly rate, that nightly rate is reduced to as zero—the discount cannot cause a nightly rate to become negative.

Examples:

• If we're pricing a 3-night stay where the AmountAfterTax values are 100, 110, and 120; and the fixed_amount_per_night is 10, then

  promotion rate = sum(AmountBeforeTax - fixed amount discount)

  300.00 = ((100 - 10) + (110 - 10) + (120 - 10))

• If we're pricing a 3-night stay where the AmountAfterTax values are 10, 50, and 100; and the fixed_amount_per_night is 20, then

  promotion rate = sum(AmountAfterTax - fixed amount discount)

  110.00 = (0 + (50 - 20) + (100 - 20))

Exactly one of percentage, fixed_amount, fixed_amount_per_night, fixed_price, or fixed_price_per_night is required.

If AmountAfterTax nightly rates are specified, then this sets the price for the stay, including taxes and fees, to the specified value. If AmountBeforeTax is specified, then whether or not AmountAfterTax is specified, this sets the pre-tax price for the stay to the specified value. It is assumed to be in the same currency as nightly rates.

If AmountAfterTax is intended to reflect a percentage tax, then setting a fixed price for AmountBeforeTax can result in inaccurate taxes and fees. In general, it is strongly recommended to use TaxFeeInfo to specify a property's taxes and fees.

Examples:

• If we're pricing a 1-night stay where AmountBeforeTax is 90, AmountAfterTax is 100, and fixed_price is 80, then the promotion rate is 80.
• If we're pricing a 1-night stay where AmountBeforeTax is 100, fixed_amount is 80, and TaxFeeInfo specifies a tax of 8%, then

  promotion rate = fixed price * (1 + percentage tax)

  86.40 = 80 * 1.08

• If we're pricing a 3-night stay where the AmountAfterTax values are 100, 110, and 120; and fixed_amount is 300, then

  promotion rate = 300

Exactly one of percentage, fixed_amount, fixed_amount_per_night, fixed_price, or fixed_price_per_night is required.

If AmountAfterTax nightly rates are specified, then this sets the price for each night of stay, including taxes and fees, to the specified value. If AmountBeforeTax is specified, then whether or not AmountAfterTax is specified, this sets the pre-tax price for each night of stay to the specified value. It is assumed to be in the same currency as nightly rates.

If AmountAfterTax is intended to reflect a percentage tax, then setting a fixed price for AmountBeforeTax can result in inaccurate taxes and fees. In general, it is strongly recommended to use TaxFeeInfo to specify a property's taxes and fees.

If applied_nights is specified, then the new price is applied to the cheapest N nights.

Examples:

• If we're pricing a 2-night stay where AmountBeforeTax values are 90, 90; AmountAfterTax values are 100, 100; and fixed_price is 80, then the promotion rate is 80 + 80 = 160.
• If we're pricing a 2-night stay where AmountBeforeTax is 100, 100; fixed_amount is 80, and TaxFeeInfo specifies a tax of 8%, then the promotion rate is (80 + 80) * 1.08 = 172.8.
• If we're pricing a 3-night stay where the AmountAfterTax values are 100, 110, and 120; and fixed_amount is 110, then the promotion rate is 110 * 3 = 330.

This should only be used with percentage or fixed_amount_per_night.

The number of nights to which the discount is applied, starting with the least expensive. Must be an integer from 1 to 99. If not specified, discount is applied to all nights.

Number of required nights for the discount to be applied. Each discount is applied to a separate segment of stay nights.

For example, for a 10-night stay where stay_nights is 4 (and repeats is true), then there are two stay night segments: the 1st through 4th nights and the 5th through 8th nights; the 9th and 10th nights are not part of a stay night segment.

Whether the discount may be applied to multiple stay night segments. If false, then only the segment of stay nights at the beginning of the itinerary is discounted. If true, then any segment of stay nights is discounted.

For example, if stay_nights is 4 and the itinerary is 10 nights, then, if repeats is true, then 2 segments are discounted (nights 1-4 and nights 5-8); but, if repeats is false, then only 1 segment is discounted (nights 1-4).

Exactly one of Discount or BestDailyDiscount must be specified.

Specifies a daily discount which may be applied to a night of stay. This is in contrast with Discount, which applies discounts to entire stays.

Each property may have a single group of promotions that are considered "best daily." This means that for each night of stay, the single "best daily" promotion that is eligible and yields the deepest discount for that night is selected and may be applied.

Stacking may not be specified with BestDailyDiscount. The "best daily" discounts yielding the deepest discount for each night are combined and treated as a single stay discount (i.e. Discount) with stacking type set to base. This combined discount is compared against, and can be stacked with, other eligible <Discount> promotions to find the one or combination that provides the deepest discount. Either the combination of BestDailyDiscount or a single Discount, whichever yields the lower price, is selected and applied for the base stacking type.

StayDates can be specified with this type of discount, but the application must be set to overlap

Exactly one of percentage, fixed_amount, or fixed_price is required.

A decimal value from 0-100 which specifies the percentage discount. It is applied to AmountAfterTax (or AmountBeforeTax if AmountAfterTax isn't specified).

Examples:

• If AmountAfterTax for a night of stay is 100 and percentage is 20, then

  promotion rate = AmountAfterTax * (1 - percentage discount)

  80.00 = 100 * (1 - 0.2)

• If AmountBeforeTax for an ight of stay is 100, percentage is 20 and TaxFeeInfo specifies a tax of 10, then

  promotion rate = AmountBeforeTax * (1 - percentage discount) + tax

  90.00 = 100 * (1 - 0.2) + 10

Exactly one of percentage, fixed_amount, or fixed_price is required.

A fixed amount to be subtracted from a single AmountAfterTax nightly rate (or AmountBeforeTax nightly rate if AmountAfterTax isn't specified). It is assumed to be in the same currency as nightly rates. If this is larger than the sum of nightly rates, the resulting value is zero.

Examples:

• If AmountBeforeTax for a single night is 90, AmountAfterTax is 100, and fixed_amount is 20, then

  promotion rate = AmountAfterTax - fixed discount

  80.00 = 100 - 20

• If AmountBeforeTax for a single night is 100, fixed_amount is 20, and TaxFeeInfo specifies a tax of 8%, then

  promotion rate = (AmountBeforeTax - fixed discount) * (1 + percentage tax)

  86.40 = (100 - 20) * 1.08

Exactly one of percentage, fixed_amount, or fixed_price is required.

If AmountAfterTax nightly rates are specified, then this sets the price for the night of stay, including taxes and fees, to the specified value. If AmountBeforeTax is specified, then whether or not AmountAfterTax is specified, this sets the pre-tax price for the stay to the specified value. It is assumed to be in the same currency as nightly rates.

Examples:

• If AmountBeforeTax for a single night is 90, AmountAfterTax is 100, and fixed_price is 80, then the promotion rate is 80.
• If AmountBeforeTax for a single night is 100, fixed_amount is 80, and TaxFeeInfo specifies a tax of 8%, then

  promotion rate = fixed price * (1 + percentage tax)

  86.40 = 80 * 1.08

Container for a membership rate rule that triggers a specific UI treatment for the associated discount.

This element should not be specified unless <Discount> is also specified.

ID of the rate rule associated with a membership program.

Multiple promotions can be applied to a single rate depending on this setting:

• any: Can be combined with any other promotion (except none), but the order in which the promotions should be applied is not guaranteed.
• base: The best eligible base promotion is selected and applied first, before other promotions. This was previously named base_only.
• second: The best eligible second promotion is selected and applied after a base promotion (if applicable) and before any promotions.
• none: Can not be combined with other promotions.

Of the allowed combinations, the set of promotions which yields the largest discount are applied to the rate.

Describes how the promotion should be applied.

Valid values are:

• all: Applies the promotion to each night in the itinerary if all dates in the itinerary overlap with the stay dates.
• any: Applies the promotion to all nights in the itinerary if any date in the itinerary overlaps with a date in the stay dates range.
• overlap: Applies the promotion only to those nights in the itinerary that overlap with a date in the stay dates range.

This attribute must always be specified.

• If <Discount> specifies percentage and application is set to all or any, the discount is applied as a percentage of the full stay.
• If <Discount> specifies percentage and application is set to overlap, the discount is applied as a percentage of nightly rates for overlapping nights.
• <Discount> specifying fixed_amount and application set to overlap is an invalid combination.
• <FreeNights> supports all application values. Note that for overlap, only overlapping nights of stay are considered for the discount requirements.

A date range specifying dates when the promotion is to be applied.

The YearlessDate format is also supported.

• If one of start or end is a yearless date, both must be populated as yearless dates.
• Yearless date ranges must not wrap around the new year. Instead, represent the range as two adjacent date ranges. For example, {"12-29", "01-05"} can be represented as {"12-29", "12-31"} and {"01-01", "01-05"}.

The days of the week that are allowed in the date range. If not specified, all days are allowed in the date range. Each character in the string specifies a day. For example, "MTWHF" specifies that weekdays are allowed in the date range.

Valid characters are:

• M for Monday
• T for Tuesday
• W for Wednesday
• H for Thursday
• F for Friday
• S for Saturday
• U for Sunday

Any character combination is valid.

Valid values are include and exclude.

If the UserCountries type is set as include, the promotion applies to users from the listed countries.

If the UserCountries type is exclude, the promotion applies to users from outside the listed countries.

If the UserCountries type is unset, it is treated as include and the promotion is applied to users from the listed countries.

Either <Success> or <Issues> is present in each message.

Either <Success> or <Issues> is present in each message.

The type of issue encountered.

Valid values are warning, error, and failure.