Promotions

Syntax

The Promotions message uses the following syntax:
<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="partner_account_name"
            id="message_ID"
            timestamp="timestamp">
  <HotelPromotions hotel_id="HotelID" action="[overlay]">
    <Promotion id="PromotionID" action="[delete]">
      <RoomTypes>
        <RoomType id="RoomID_1">
        <RoomType id="RoomID_2">
      <RoomTypes/>
      <RatePlans>
        <RatePlan id="PackageID_1">
        <RatePlan id="PackageID_2">
      <RatePlans/>
      <BookingDates>
        <DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week="MTWHFSU_or_subset"/>
        <DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week="MTWHFSU_or_subset"/>
      <BookingDates/>
      <CheckinDates>
        <DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week="MTWHFSU_or_subset"/>
      <CheckinDates/>
      <BookingWindow min="integer" max="integer"/>
      <LengthOfStay min="integer" max="integer"/>
      <!-- Specify either a percentage or fixed_amount (but not both) -->
      <Discount percentage="float" fixed_amount="float" applied_nights="integer_1_to_99"/>
      <MinimumAmount before_discount="integer"/>
      <Devices>
        <Device type="[desktop|tablet|mobile]"/>
      </Devices>
      <UserCountries>
        <Country code="country_code"/>
      </UserCountries>
    </Promotion>
  </HotelPromotions>
</Promotions>

Elements & Attributes

The Promotions message has the following elements and attributes:
Element / @Attribute Occurrences Type Description
Promotions 1 Complex element The root element of a promotions message.
Promotions / @partner 1 String The partner account for this message. To get this value, contact us.

Note: 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 / @id 1 String A unique identifier for the request. This value is returned in the response and in error and warning messages. Allowed characters are a-z, A-Z, 0-9, _ (underscore), and - (dash).
Promotions / @timestamp 1 DateTime The creation date and time of this message.
Promotions / HotelPromotions 0..n HotelPromotions Promotions for a property. Each promotion applies to a single property.
Promotions / HotelPromotions / @hotel_id 1 String The unique identifier for the property. This value must match the Hotel ID specified using <id> in the <listing> element in the Hotel List Feed. The Hotel ID is also listed in Hotel Center.
Promotions / HotelPromotions / @action 0..1 Enum

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")
Promotions / HotelPromotions / Promotion 0..10 Promotion

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

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

Promotions / HotelPromotions / Promotion / @id 1 String A unique identifier for the promotion. The maximum number of characters allowed is 40. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (dash), and . (period).
Promotions /HotelPromotions / Promotion / @action 0..1 Enum

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"/>.

Promotions / HotelPromotions / Promotion / RoomTypes 0..1 RoomTypes Container for a list of room types to which the promotion applies. The promotion is applied to each <RoomType> specified. If <RoomTypes> isn't specified, the promotion applies to all rooms.
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType 1..n RoomType Specifies a room type. A room type is defined in a <RoomData> element in a Transaction (Property Data) message and is referenced using its <RoomID> value. (Its <RoomID> value is also referenced by the InvTypeCode attribute in OTA_HotelRateAmountNotifRQ messages.)
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id 1 String The unique identifier for the inventory (room type). This value maps to <RoomID> in a Transaction (Property Data) message. The maximum number of characters allowed is 50.
Promotions / HotelPromotions / Promotion / RatePlans 0..1 RatePlans Container for a list of rate plans to which the promotion applies. If <RatePlans> isn't specified, the promotion applies to all rate plans.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan 1..n RatePlan Specifies a rate plan. A rate plan is defined by a combination of package, rates, and availability, as defined in Transaction (Property Data), OTA_HotelRateAmountNotifRQ, and OTA_HotelAvailNotifRQ messages, and as identified by the PackageID.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id 1 String The unique identifier for the rate plan. This value maps to the PackageID value in <PackageData> in a Transaction (Property Data) message, and in the RatePlanCode attribute in <StatusApplicationControl> in both <OTA_HotelRateAmountNotifRQ> and <OTA_HotelAvailNotifRQ> messages. The maximum number of characters allowed is 50.
Promotions / HotelPromotions / Promotion / BookingDates 0..1 BookingDates A container for one or more date ranges that define when booking must occur in order for the promotion to be applied.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange 1..20 DateRange A date range specifying when booking must occur for the promotion to be applied.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start 1 Date The starting date (based on the property's time zone), inclusive, of the date range. This date must be before, or the same as, the end date.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end 1 Date The ending date (based on the property's time zone), inclusive, of the date range. This date must be the same as, or after, the start date.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week 0..1 String

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.

Promotions / HotelPromotions / Promotion / CheckinDates 0..1 CheckinDates A container for one or more date ranges that define when check-in must occur for the promotion to be applied.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange 1..20 DateRange 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.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @start 1 Date The starting date (based on the property's time zone), inclusive, of the date range. This date must be before, or the same as, the end date.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end 1 Date The ending date (based on the property's time zone), inclusive, of the date range. This date must be the same as, or after, the start date.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week 0..1 String

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.

Promotions / HotelPromotions / Promotion / BookingWindow 0..1 BookingWindow Specifies the time period when booking must occur relative to the check-in date (based on the property's time zone). For example, the booking window can be set to least 7 days, but not more than 180 days, prior to check-in.
Promotions / HotelPromotions / Promotion / BookingWindow / @min 0..1 Integer The minimum number of days prior to check-in when booking must occur for the promotion to be applied. If this isn't specified, there is no minimum.
Promotions / HotelPromotions / Promotion / BookingWindow / @max 0..1 Integer The maximum number of days prior to check-in when booking must occur for the promotion to be applied. If this isn't specified, there is no maximum.
Promotions / HotelPromotions / Promotion / LengthOfStay 0..1 LengthOfStay Defines the minimum and maximum nights allowed in the stay.
Promotions / HotelPromotions / Promotion / LengthOfStay / @min 0..1 Integer The minimum nights allowed in the stay for the promotion to be applied. If this isn't specified, there is no minimum.
Promotions / HotelPromotions / Promotion / LengthOfStay / @max 0..1 Integer The maximum nights allowed in the stay for the promotion to be applied. If this isn't specified, there is no maximum.
Promotions / HotelPromotions / Promotion / Discount 1 Discount Specifies the discount to be applied to the rate specified in the referenced <RatePlan> for this promotion.
Promotions / HotelPromotions / Promotion / Discount / @percentage 0..1 Float Either this or the fixed_amount attribute is required.

A decimal value from 0-100 that specifies the percentage discount to be applied to the rate defined in the referenced <RatePlan> for this promotion. For example, if the value is 20 and the referenced rate is $100, then the promotion rate is $80.

Warning: Percentage discounts are applied to AmountBeforeTax or AmountAfterTax specified in <BaseByGuestAmount> elements in OTA_HotelRateAmountNotifRQ messages. However, We strongly recommend using a percentage discount only with AmountBeforeTax and not with AmountAfterTax (instead, don't specify AmountAfterTax and use TaxFeeInfo to specify taxes and fees).

Promotions / HotelPromotions / Promotion / Discount / @fixed_amount 0..1 Float Either this or the percentage attribute is required.

Fixed discount to be applied to the sum of nightly rates. Assumed to be in the same currency as nightly rates. If larger than the sum of nightly rates, the resulting rate will be zero.

Warning: Fixed amount discounts are applied to AmountBeforeTax or AmountAfterTax specified in <BaseByGuestAmount> elements in OTA_HotelRateAmountNotifRQ messages. We strongly recommend using a fixed amount discount only with AmountBeforeTax and not with AmountAfterTax (instead, don't specify AmountAfterTax and use TaxFeeInfo to specify taxes and fees).

Promotions / HotelPromotions / Promotion / Discount / @applied_nights 0..1 Integer 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.
Promotions / HotelPromotions / Promotion / MinimumAmount 0..1 MinimumAmount Specifies the minimum sum of the daily room rates (using the larger of AmountBeforeTax or AmountAfterTax) that must be exceeded for the promotion to be applied.
Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount 1 Integer The value that must be exceeded for the promotion to be applied.
Promotions / HotelPromotions / Promotion / Devices 0..1 Devices Container for listing the user devices that are eligible for the promotion. If specified, only eligible users on the listed devices are offered the discounted rate. If not specified, eligible users on any device are offered the discounted rate.
Promotions / HotelPromotions / Promotion / Devices / Device 1..3 Device Defines one type of user device that is eligible for the promotion.
Promotions / HotelPromotions / Promotion / Devices / Device / @type 1 Enum A type of device. The value must be desktop, tablet, or mobile.
Promotions / HotelPromotions / Promotion / UserCountries 0..1 UserCountries Container for listing the user locations (countries) that are eligible for the promotion. If specified, only eligible users in the listed countries are offered the discounted rate. If not specified, eligible users in any country are offered the discounted rate.
Promotions / HotelPromotions / Promotion / UserCountries / Country 1..50 Country Defines one country where users are eligible for the promotion.
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code 1 String A CLDR country code, such as DE or FR. Note that, for some countries, the CLDR country code isn't the same as the 2-letter ISO country code. Also, CLDR region codes are not supported.

Examples

Basic message

The following example shows a basic Promotions message:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <RoomTypes>
         <RoomType id="123"/>
         <RoomType id="456"/>
      </RoomTypes>
      <RatePlans>
         <RatePlan id="234"/>
         <RatePlan id="567"/>
      </RatePlans>
      <BookingDates>
         <DateRange start="2020-07-01" end="2020-07-31" days_of_week="MTWHF"/>
         <DateRange start="2020-09-01" end="2020-09-30"/>
      </BookingDates>
      <CheckinDates>
         <DateRange start="2020-10-01" end="2020-10-31" days_of_week="FSU"/>
      </CheckinDates>
      <BookingWindow min="7" max="330"/>
      <LengthOfStay min="2" max="14"/>
      <Discount percentage=".2" applied_nights="2"/>
      <Devices>
        <Device type="mobile"/>
        <Device type="tablet"/>
      </Devices>
      <UserCountries>
        <Country code="US"/>
        <Country code="UK"/>
      </UserCountries>
    </Promotion>
  </HotelPromotions>
</Promotions>

Delete one promotion

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

<?xml version="1.0" encoding="UTF-8"?>
<Promotions timestamp="2020-06-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1" action="delete"/>
  </HotelPromotions>
</Promotions>

Delete all promotions

The following example shows how to delete all promotions for a property:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions timestamp="2020-07-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1" action="overlay"/>
</Promotions>

Overlay all promotions

The following example shows how to overlay <HotelPromotions> for a property with one or more new promotions. When action="overlay", all stored promotions are deleted prior to storing the promotions specified in the current message:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions timestamp="2020-07-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1" action="overlay"/>
    <Promotion id="1">
      <RoomTypes>
         <RoomType id="123"/>
         <RoomType id="456"/>
      </RoomTypes>
      <RatePlans>
         <RatePlan id="234"/>
         <RatePlan id="567"/>
      </RatePlans>
      <BookingDates>
         <DateRange start="2020-09-01" end="2020-09-30"/>
      </BookingDates>
      <Discount percentage=".1"/>
    </Promotion>
  </HotelPromotions>
</Promotions>