推广

概览

借助此 API，您可以指定可能的折扣。在指定的促销活动中，Google 会应用可用的促销活动或促销活动组，以使价格最低。如果您正在寻找一个支持任意费率调整的 API，以便在满足条件时上调或下调价格，不妨考虑使用我们的 Rate Modifications API。请注意，如果同时使用这两个 API，系统会先应用房价更改，然后再应用促销优惠。

请求

语法

Promotions 消息使用以下语法：

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner= "partner_key"
            id="message_ID"
            timestamp="timestamp">
  <HotelPromotions hotel_id="HotelID" action="[overlay]">
    <Promotion id="PromotionID" action="[delete]">
      <BookingDates>
        <DateRange start="YYYY-MM-DD[THH:mm:ss]" end="YYYY-MM-DD[THH:mm:ss]"
          days_of_week="MTWHFSU_or_subset"/>
        <DateRange start="YYYY-MM-DD[THH:mm:ss]" end="YYYY-MM-DD[THH:mm:ss]"
          days_of_week="MTWHFSU_or_subset"/>
      </BookingDates>
      <BookingWindow min="integer_or_duration" max="integer_or_duration"/>
      <Ceiling amount_per_night="float"/>
      <Floor amount_per_night="float"/>
      <CheckinDates>
        <DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </CheckinDates>
      <CheckoutDates>
        <DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </CheckoutDates>
      <!-- Specify only one of percentage, percentage_of_base, fixed_amount,
           fixed_amount_per_night, fixed_price, or fixed_price_per_night;
           applied_nights is only used with percentage, fixed_amount_per_night,
           and fixed_price_per_night. -->
      <Discount percentage="float" percentage_of_base="float"
                fixed_amount="float" fixed_amount_per_night="float"
                fixed_price="float" fixed_price_per_night="float"
                applied_nights="integer_1_to_99" rank="integer_1_to_99">
        <!-- FreeNights may not be used in conjunction with attributes on Discount -->
        <FreeNights stay_nights="integer" discount_nights="integer"
                    discount_percentage="float" night_selection="[cheapest|last]"
                    repeats="boolean"/>
      </Discount>
      <!-- Exactly one of Discount or BestDailyDiscount must be specified.
           Specify only one of percentage, fixed_amount, or fixed_price. -->
      <BestDailyDiscount percentage="float" fixed_amount="float" fixed_price="float"/>
      <Devices>
        <Device type="[desktop|tablet|mobile]"/>
      </Devices>
      <InventoryCount min="integer" max="integer"/>
      <LengthOfStay min="integer" max="integer"/>
      <MembershipRateRule id="RateRuleID"/>
      <MinimumAmount before_discount="integer"/>
      <Occupancy min="integer" max="integer"/>
      <RatePlans>
        <RatePlan id="PackageID_1"/>
        <RatePlan id="PackageID_2"/>
      </RatePlans>
      <RoomTypes>
        <RoomType id="RoomID_1"/>
        <RoomType id="RoomID_2"/>
      </RoomTypes>
      <Stacking type="[any|base|none|second]"/>
      <StayDates application="[all|any|overlap]">
        <DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </StayDates>
      <UserCountries type="[include|exclude]">
        <Country code="country_code"/>
      </UserCountries>
    </Promotion>
  </HotelPromotions>
</Promotions>

元素和属性

促销信息消息包含以下元素和属性：

元素 / @Attribute 出现次数 类型 说明
Promotions 1 Complex element 促销信息的根元素。
Promotions / @partner 1 string 此消息对应的合作伙伴账号。此字符串值是 Hotel Center “账号设置”页面上列出的“合作伙伴键”值。

如果您的后端为多个账号提供 Feed，则此值需要与同一账号的 <OTA_HotelRateAmountNotifRQ> 和 <OTA_HotelAvailNotifRQ> 消息的 <RequestorID> 元素中指定的 ID 属性值一致。
Promotions / @id 1 string 此请求消息的唯一标识符。此值会在响应消息中返回。允许使用的字符包括 a-z、A-Z、0-9、_（下划线）和 -（短划线）。
Promotions / @timestamp 1 DateTime 此消息的创建日期和时间。
Promotions / HotelPromotions 0..n HotelPromotions

酒店的促销活动。每个促销活动都适用于单个房源。

如果有多个促销活动符合条件，除非使用 <Stacking>，否则系统会将折扣幅度最大的促销活动应用于预订。
Promotions / HotelPromotions / @hotel_id 1 string 房源的唯一标识符。此值必须与酒店列表 Feed 中 <listing> 元素中使用 <id> 指定的酒店 ID 一致。酒店 ID 也列在 Hotel Center 中。
Promotions / HotelPromotions / @action 0..1 enum

如果指定，值必须为 "overlay"。当值为 "overlay" 时，系统会先删除所有已存储的促销活动，然后再存储当前消息中指定的促销活动。

如果未指定，则当前消息中指定的每个促销活动都属于以下任一类别：

  • Added（如果存储的所有促销活动都没有相同的 id）
  • Updated（如果存储的促销活动具有相同的 id）
  • Deleted（如果存储的促销活动具有相同的 id，并且当前消息中指定的促销活动的 action 属性的值为 "delete"）
Promotions / HotelPromotions / Promotion 0..99 Promotion

针对房源的单个促销活动。请注意，如果未指定 action="overlay" 和 <Promotion>，系统会删除相应媒体资源的所有促销活动。

如果您需要使用超过 99 项促销活动，请与您的技术支持客户经理 (TAM) 联系。
Promotions / HotelPromotions / Promotion / @id 1 string 促销活动的唯一标识符。允许的字符数上限为 40 个字符。允许使用的字符包括 a-z、A-Z、0-9、_（下划线）、-（短划线）和 . （英文句点）。
Promotions /HotelPromotions / Promotion / @action 0..1 enum

如果指定，值必须为 delete。如果未指定，并且系统未存储具有相同 id 的促销活动，则系统会存储此促销活动。否则，如果未指定，并且存储了具有相同 id 的促销活动，则系统会更新现有促销活动。

如果指定了 delete，系统会删除具有相同 id 的已存促销活动。 使用 delete 时，请勿在 <Promotion> 中添加任何子元素。此外，不允许将 delete 与 <HotelPromotions action="overlay"/> 结合使用。
Promotions / HotelPromotions / Promotion / BookingDates 0..1 BookingDates 一个或多个范围的容器，用于定义必须在何时进行预订才能应用促销优惠。
Promotions / HotelPromotions / Promotion / BookingDates / DateRange 1..99 DateRange 一个范围，用于指定必须在什么时间范围内进行预订才能应用促销优惠。
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start 0..1 Date 或 DateTime

范围的开始日期或日期时间（基于媒体资源所在的时区），包括该日期/时间。

  • start 指定的日期或日期时间必须早于（或等于）end 指定的日期或日期时间。
  • 如果未指定 start，则在开始时间方面，范围实际上是无限的。
  • 如果 start 填充为日期“YYYY-MM-DD”，则会被解读为日期时间“YYYY-MM-DDT00:00:00”。
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end 0..1 Date 或 DateTime

范围的结束日期或日期时间（基于媒体资源所在的时区），包括该日期/时间。

  • end 指定的日期或日期时间必须晚于（或等于）start 指定的日期或日期时间。
  • 如果未指定 end，则在结束时间方面，范围实际上是无限的。
  • 如果 end 以日期“YYYY-MM-DD”的形式提供，则会被解读为日期时间“YYYY-MM-DDT23:59:59”。
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week 0..1 string

日期范围内允许的星期几。如果未指定，则日期范围内的所有日期均可。字符串中的每个字符都指定一天。例如，“MTWHF”表示日期范围内允许包含周一至周五。

有效字符包括：

  • M 表示周一
  • T 表示周二
  • W 表示周三
  • H 表示周四
  • F 表示周五
  • S 表示周六
  • U 表示周日

任何字符组合均有效。
Promotions / HotelPromotions / Promotion / BookingWindow 0..1 BookingWindow 指定相对于入住日期的预订必须完成的时间段（基于房源所在的时区）。例如，您可以将预订期限设置为入住前至少 7 天，但不超过 180 天。
Promotions / HotelPromotions / Promotion / BookingWindow / @min 0..1 integer or duration 预订必须在入住前至少提前多少天，促销优惠才会应用。如果未指定此值或其值为 0，则没有最小值。

有效的值类型包括：

  • 整数：入住日期前的天数。例如，值为 30 表示促销优惠仅适用于入住日期前至少 30 天的预订。
  • ISO 8601 时长（天、小时和分钟）：入住日期前的天数（可选小时/分钟）。例如，值为 P30D 表示促销优惠仅适用于入住日期前至少 30 天的预订。如果值为 P30DT6H，则要求在抵达前 30 天的 18:00 当天或之前进行预订。
Promotions / HotelPromotions / Promotion / BookingWindow / @max 0..1 integer or duration 预订必须在入住前多少天内完成，促销优惠才会应用。如果未指定此值或其值为 0，则没有上限。

有效的值类型包括：

  • 整数：入住日期前的天数。例如，值为 30 表示促销仅适用于入住日期前最多 30 天的预订。
  • ISO 8601 时长（天、小时和分钟）：入住日期前的天数（可选小时/分钟）。例如，值为 P30D 表示促销仅适用于入住日期前最多 30 天的预订。如果值为 P30DT6H，则需要在入住前 30 天的 18:00 或之后进行预订。
Promotions / HotelPromotions / Promotion / Ceiling 0..1 Ceiling

定义应用促销优惠后费率可设置的最大值。

促销活动始终必须指定 <Discount> 或 <BestDailyDiscount>，因此，若要创建仅应用 <Ceiling> 的促销活动，一种方法是设置 <Discount>，并将 percentage 设为 0。

如果配置了堆叠，则可以对单次住宿应用多个包含 <Ceiling> 的促销优惠。每个促销活动都会应用其折扣，紧随其后的是上限。以下示例展示了每个上限如何影响堆栈中的下一次促销计算。

示例：

计算入住 1 晚的价格，其中 AmountBeforeTax 为 100，并且有两个叠加的促销：

  1. 促销活动，堆叠类型为 base，fixed_amount 为 25，上限 amount_per_night 为 60
  2. 促销活动，堆叠类型为 second，fixed_amount 为 25，上限 amount_per_night 为 90

计算顺序如下：

  1. 系统会先应用 base 促销，将 AmountBeforeTax 折扣为 75，但上限会将其降至 60。
  2. second 促销活动将 AmountBeforeTax 的折扣从 60 降至 35。此值低于上限 90，因此不会应用第二个上限。最终费率为 35。

60 是一个更严格的总上限，但这无关紧要，因为它仅适用于其自身的促销活动，并且无法有一个涵盖整个促销活动堆栈的上限。
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night 1 float

应用折扣后，每晚费率可设置的最高金额。

如果还指定了 <Floor> 元素，则此值必须设置为大于或等于 <Floor> 中的 amount_per_night 属性的值。

当税费和其他费用包含在使用 AmountAfterTax 计算的每晚费率中时，系统会对其应用 amount_per_night，但不会对使用 TaxFeeInfo 指定的税费和其他费用应用 amount_per_night。
Promotions / HotelPromotions / Promotion / Floor 0..1 Floor

定义应用促销优惠后费率可设置的最小值的限制。

促销活动始终必须指定 <Discount> 或 <BestDailyDiscount>，因此，若要创建仅应用 <Floor> 的促销活动，一种方法是设置 <Discount>，并将 percentage 设为 0。

即使免费晚间住宿已应用 100% 折扣，<Floor> 逻辑仍适用于 <FreeNights> 折扣。

如果配置了堆叠，则可以对单次住宿应用多个包含 <Floor> 的促销优惠。每个促销活动都会应用其折扣，紧随其后的是其底价。以下示例展示了每个楼层如何影响堆栈中的下一次促销计算。

示例：

计算入住 1 晚的价格，其中 AmountBeforeTax 为 100，并且有两个叠加的促销：

  1. 促销活动，堆叠类型为 base，fixed_amount 为 25，amount_per_night 为 90
  2. 促销活动，堆叠类型为 second，fixed_amount 为 25，amount_per_night 为 60

计算顺序如下：

  1. 系统会先应用 base 促销，将 AmountBeforeTax 的折扣金额减至 75，但最低金额将其上调至 90。
  2. second 促销活动将 AmountBeforeTax 的价格从 90 降至 65。此值高于下限 60，因此不会应用第二个下限。最终费率为 65。

90 是一个更严格的整体下限，但这无关紧要，因为它仅适用于其自身的促销活动，并且没有任何单一下限可涵盖整个促销活动堆叠。
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night 1 float

折扣应用后，每晚房价可设置的最低金额。

如果还指定了 <Ceiling> 元素，则此值必须设置为小于或等于 <Ceiling> 中的 amount_per_night 属性的值。

当税费和其他费用包含在使用 AmountAfterTax 计算的每晚费率中时，系统会对其应用 amount_per_night，但不会对使用 TaxFeeInfo 指定的税费和其他费用应用 amount_per_night。
Promotions / HotelPromotions / Promotion / CheckinDates 0..1 CheckinDates 一个或多个日期范围的容器，用于定义必须在何时完成入住才能应用促销优惠。
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange 1..20 DateRange

指定必须在何时入住才能应用促销优惠的日期范围。如果您要删除一个或多个促销活动，则无需此元素。

也支持 YearlessDate 格式。

  • 如果 start 或 end 之一是无年份日期，则必须将这两个日期都填充为无年份日期。
  • 不含年份的日期范围不得跨越新年。请改为将该范围表示为两个相邻的日期范围。例如，{"12-29", "01-05"} 可以表示为 {"12-29", "12-31"} 和 {"01-01", "01-05"}。
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @start 0..1 Date or YearlessDate 日期范围的开始日期（基于媒体资源所在的时区），包括该日期。此日期必须早于 end 日期或与之相同。如果未指定 start，则日期范围在开始日期方面实际上是无限的。
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end 0..1 Date or YearlessDate 日期范围的结束日期（以媒体资源所在的时区为准），含此日期。此日期必须与 start 日期相同或晚于该日期。如果未指定 end，则日期范围在结束日期方面实际上是无限的。
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week 0..1 string

日期范围内允许的星期几。如果未指定，则日期范围内的所有日期均可。字符串中的每个字符都指定一天。例如，“MTWHF”表示日期范围内允许包含周一至周五。

有效字符包括：

  • M 表示周一
  • T 表示周二
  • W 表示周三
  • H 表示周四
  • F 表示周五
  • S 表示周六
  • U 表示周日

任何字符组合均有效。
Promotions / HotelPromotions / Promotion / CheckoutDates 0..1 CheckoutDates 一个或多个日期范围的容器，用于定义必须在什么时间结账才能应用促销优惠。
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange 1..20 DateRange

指定必须在什么时间退房才能应用促销优惠的日期范围。如果您要删除一项或多项促销活动，则无需此元素。

也支持 YearlessDate 格式。

  • 如果 start 或 end 之一是无年份日期，则必须将这两个日期都填充为无年份日期。
  • 不含年份的日期范围不得跨越新年。请改为将该范围表示为两个相邻的日期范围。例如，{"12-29", "01-05"} 可以表示为 {"12-29", "12-31"} 和 {"01-01", "01-05"}。
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @start 0..1 Date or YearlessDate 日期范围的开始日期（基于媒体资源所在的时区），包括该日期。此日期必须早于 end 日期或与之相同。如果未指定 start，则日期范围在开始日期方面实际上是无限的。
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end 0..1 Date or YearlessDate 日期范围的结束日期（以媒体资源所在的时区为准），含此日期。此日期必须与 start 日期相同或晚于该日期。如果未指定 end，则日期范围在结束日期方面实际上是无限的。
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @days_of_week 0..1 string

日期范围内允许的星期几。如果未指定，则日期范围内的所有日期均可。字符串中的每个字符都指定一天。例如，“MTWHF”表示日期范围内允许包含周一至周五。

有效字符包括：

  • M 表示周一
  • T 表示周二
  • W 表示周三
  • H 表示周四
  • F 表示周五
  • S 表示周六
  • U 表示周日

任何字符组合均有效。
Promotions / HotelPromotions / Promotion / Devices 0..1 Devices 用于列出符合促销条件的用户设备的容器。如果指定了此属性，则只有列出的设备上的符合条件的用户才能享受折扣优惠。如果未指定，则系统会向任何设备上的符合条件的用户提供折扣费率。
Promotions / HotelPromotions / Promotion / Devices / Device 1..3 Device 定义符合促销条件的一种用户设备。
Promotions / HotelPromotions / Promotion / Devices / Device / @type 1 enum 一种设备类型。值必须为 desktop、tablet 或 mobile。
Promotions / HotelPromotions / Promotion / Discount 1 Discount

必须指定 Discount 或 BestDailyDiscount 中的一个。

指定要为此促销活动应用的折扣。
Promotions / HotelPromotions / Promotion / Discount / @percentage 0..1 float

必须提供 percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 中的一个。

一个介于 0 到 100 之间的小数值，用于指定折扣百分比。 它会应用于 AmountAfterTax（如果未指定 AmountAfterTax，则应用于 AmountBeforeTax）。

示例：

  • 如果 AmountAfterTax 为 100，percentage 为 20，则

    促销费率 = AmountAfterTax * (1 - 折扣百分比)

    80.00 = 100 * (1 - 0.2)

  • 如果 AmountBeforeTax 为 100，percentage 为 20，并且 TaxFeeInfo 指定了 10 的税费，则

    促销折扣率 = AmountBeforeTax * (1 - 折扣百分比) + 税费

    90.00 = 100 * (1 - 0.2) + 10
Promotions / HotelPromotions / Promotion / Discount / @percentage_of_base 0..1 float

必须提供 percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 中的一个。

一个介于 0 到 100 之间的十进制值，用于指定基础折扣的百分比。与 percentage 类似，它会应用于 AmountAfterTax（如果未指定 AmountAfterTax，则应用于 AmountBeforeTax）。

与 percentage 不同，无论之前应用了哪些促销优惠，此折扣始终按占基准费率的百分比计算。

示例：

  • 假设我们有两项促销活动，分别按顺序应用于价格为 100 元的单晚住宿。第一个是常规的 10% 折扣，第二个是基础折扣的 10%。那么折扣率将为 80，因为这两项促销活动都会按 10 折扣减。请注意，如果第二项促销活动也是按百分比折扣，那么折扣率将为 81，因为第二项促销活动会按 90 的 10% 折扣。
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount 0..1 float

必须提供 percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 中的一个。

从 AmountAfterTax 每晚费率的总和（如果未指定 AmountAfterTax，则为 AmountBeforeTax 每晚费率的总和）中减去的固定金额。假定其币种与每晚费率相同。如果此值大于每晚费率的总和，则结果为零。

示例：

  • 如果我们要为 1 晚的住宿费用定价，其中 AmountBeforeTax 为 90、AmountAfterTax 为 100，fixed_amount 为 20，则

    促销折扣率 = AmountAfterTax - 固定折扣

    80.00 = 100 - 20

  • 如果我们要为 1 晚的住宿定价，其中 AmountBeforeTax 为 100，fixed_amount 为 20，TaxFeeInfo 指定税率为 8%，则

    促销折扣率 = (AmountBeforeTax - 固定折扣) * (1 + 税率百分比)

    86.40 = (100 - 20) * 1.08

  • 如果我们要为 1 晚的住宿定价，其中 AmountBeforeTax 为 50，fixed_amount 为 60，TaxFeeInfo 指定的税费为 10，则

    促销折扣率 = (AmountBeforeTax - 固定折扣) * 税率

    10.00 = 0 + 10

  • 如果我们要为 3 晚的住宿定价，其中 AmountAfterTax 值分别为 100、110 和 120，fixed_amount 为 150，则

    促销率 = sum(AmountAfterTax) - (fixed discount)

    180.00 = (100 + 110 + 120) - 150
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night 0..1 float

必须提供 percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 中的一个。

应用于每个 AmountAfterTax 每晚费率（如果指定了 applied_nights，则应用于最便宜的 N 个每晚费率）的固定折扣。如果未指定 AmountAfterTax，则系统会将其应用于 AmountBeforeTax。假定其币种与每晚费率相同。如果 fixed_amount_per_night 大于每晚费率，则将该每晚费率减为零；折扣不能导致每晚费率变为负数。

示例：

  • 如果我们要为 3 晚的住宿价格定价，其中 AmountAfterTax 值分别为 100、110 和 120，fixed_amount_per_night 为 10，则

    促销折扣率 = sum(AmountBeforeTax - 固定金额折扣)

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

  • 如果我们要为 3 晚的住宿价格定价，其中 AmountAfterTax 值分别为 10、50 和 100，fixed_amount_per_night 为 20，则

    促销折扣率 = sum(AmountAfterTax - 固定金额折扣)

    110.00 = (0 + (50 - 20) + (100 - 20))
Promotions / HotelPromotions / Promotion / Discount / @fixed_price 0..1 float

必须提供 percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 中的一个。

如果指定了 AmountAfterTax 每晚费率，则此属性会将住宿价格（含税费及其他费用）设置为指定的值。如果指定了 AmountBeforeTax，则无论是否指定了 AmountAfterTax，系统都会将住宿的税前价格设置为指定的值。假定其币种与每晚费率相同。

如果 AmountAfterTax 旨在反映百分比税率，则为 AmountBeforeTax 设置固定价格可能会导致税费不准确。一般来说，强烈建议使用 TaxFeeInfo 来指定房源的税费。

示例：

  • 如果我们要为 1 晚的住宿定价，其中 AmountBeforeTax 为 90、AmountAfterTax 为 100，fixed_price 为 80，则促销费率为 80。
  • 如果我们要为 1 晚的住宿定价，其中 AmountBeforeTax 为 100，fixed_amount 为 80，TaxFeeInfo 指定税率为 8%，则

    促销折扣率 = 固定价格 *（1 + 税率）

    86.40 = 80 * 1.08

  • 如果我们要为 3 晚的住宿定价，其中 AmountAfterTax 值分别为 100、110 和 120，fixed_amount 为 300，则

    促销费率 = 300
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night 0..1 float

必须提供 percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 中的一个。

如果指定了 AmountAfterTax 每晚房价，则此属性会将每晚住宿费用（含税费及其他费用）设为指定的值。如果指定了 AmountBeforeTax，则无论是否指定了 AmountAfterTax，系统都会将每晚的税前价格设置为指定的值。假定其币种与每晚费率相同。

如果 AmountAfterTax 旨在反映百分比税率，则为 AmountBeforeTax 设置固定价格可能会导致税费不准确。一般来说，强烈建议使用 TaxFeeInfo 来指定房源的税费。

如果指定了 applied_nights，则新价格会应用于最便宜的 N 晚。

示例：

  • 如果我们要为 2 晚的住宿定价，其中 AmountBeforeTax 值为 90、90；AmountAfterTax 值为 100、100；fixed_price 为 80，则促销费率为 80 + 80 = 160。
  • 如果我们要为 2 晚的住宿定价，其中 AmountBeforeTax 为 100、100；fixed_amount 为 80，并且 TaxFeeInfo 指定了 8% 的税费，则促销折扣率为 (80 + 80) * 1.08 = 172.8。
  • 如果我们要为 3 晚的住宿定价，其中 AmountAfterTax 值分别为 100、110 和 120，fixed_amount 为 110，则促销费率为 110 * 3 = 330。
Promotions / HotelPromotions / Promotion / Discount / @applied_nights 0..1 integer

此标志应仅与 percentage 或 fixed_amount_per_night 一起使用。

折扣适用的晚数，从最便宜的晚数开始。必须是 1 到 99 之间的整数。如果未指定，则折扣会应用于所有晚数。
Promotions / HotelPromotions / Promotion / Discount / FreeNights 0..1 FreeNights 指定在满足最短住宿晚数要求时，对住宿的特定晚数提供折扣。如果使用此元素，则不允许在父 Discount 元素上设置属性。
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights 1 integer

需要入住多少晚才能享受折扣。每个折扣都适用于单独的住宿晚数。

例如，对于 10 晚的住宿，如果 stay_nights 为 4（且 repeats 为 true），则有两个住宿晚数段：第 1 晚至第 4 晚和第 5 晚至第 8 晚；第 9 晚和第 10 晚不属于任何住宿晚数段。
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights 1 integer 每个住宿晚数细分中的折扣晚数。
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage 1 float 适用于折扣晚数的折扣。如果此值为 50，则所选每晚的折扣幅度为 5 折。
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection 1 string 必须是 cheapest 或 last。如果值为 last，则住宿晚数段结束时的晚数会享受折扣。如果为 cheapest，则对住宿晚数细分范围内最便宜的晚数提供折扣。
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats 1 boolean

折扣是否可应用于多个住宿晚数细分。如果为 false，则仅会对行程开头的住宿晚数段进行折扣。如果值为 true，则对任意住宿晚数段都会应用折扣。

例如，如果 stay_nights 为 4，行程为 10 晚，则如果 repeats 为 true，则 2 个房段享受折扣（第 1-4 晚和第 5-8 晚）；但如果 repeats 为 false，则只有 1 个房段享受折扣（第 1-4 晚）。
Promotions / HotelPromotions / Promotion / Discount / @rank 0..1 integer 为此促销活动分配排名，并将其设为“按排名选择”，系统会仅选择排名最低的促销活动进行应用。值必须介于 1 到 99 之间（包括这两个数值）。如果多个促销活动具有相同的排名，系统会随机选择一个并应用该促销活动。
Promotions / HotelPromotions / Promotion / BestDailyDiscount 1 Discount

必须指定 Discount 或 BestDailyDiscount 中的一个。

指定可应用于住宿一晚的每日折扣。这与 Discount 不同，后者会对整个住宿应用折扣。

每个房源可以有一组被视为“每日精选”的促销活动。这意味着，对于每晚的住宿，系统都会选择并应用符合条件且可为当晚提供最大幅折扣的“每日最佳”促销优惠。

Stacking 可以使用 BestDailyDiscount 指定。其必须设置为 base 或 none。系统会将可为每晚提供最大幅折扣的“每日最佳”折扣组合起来，并将其视为单次住宿折扣（即 Discount），同时遵循配置的叠加类型。系统会将此组合折扣与其他符合条件的 <Discount> 促销活动进行比较，并可与这些促销活动叠加使用，以找出折扣力度最高的折扣或组合折扣。系统会选择 BestDailyDiscount 组合或单个 Discount（以价格较低者为准），并将其应用于 base 堆叠类型。

可以使用此类折扣指定 StayDates，但 application 必须设置为 overlap

.
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage 0..1 float

必须提供 percentage、fixed_amount 或 fixed_price 中的一个。

一个介于 0 到 100 之间的小数值，用于指定折扣百分比。 它会应用于 AmountAfterTax（如果未指定 AmountAfterTax，则应用于 AmountBeforeTax）。

示例：

  • 如果 AmountAfterTax（每晚住宿费）为 100，percentage 为 20，则

    促销费率 = AmountAfterTax * (1 - 折扣百分比)

    80.00 = 100 * (1 - 0.2)

  • 如果住宿一晚的 AmountBeforeTax 为 100，percentage 为 20，TaxFeeInfo 指定的税费为 10，则

    促销折扣率 = AmountBeforeTax * (1 - 折扣百分比) + 税费

    90.00 = 100 * (1 - 0.2) + 10
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount 0..1 float

必须提供 percentage、fixed_amount 或 fixed_price 中的一个。

从单个 AmountAfterTax 每晚房价（如果未指定 AmountAfterTax，则为 AmountBeforeTax 每晚房价）中扣除的固定金额。假定其币种与每晚费率相同。如果此值大于每晚费率的总和，则结果为零。

示例：

  • 如果单晚的 AmountBeforeTax 为 90，AmountAfterTax 为 100，fixed_amount 为 20，则

    促销折扣率 = AmountAfterTax - 固定折扣

    80.00 = 100 - 20

  • 如果单晚的 AmountBeforeTax 为 100，fixed_amount 为 20，TaxFeeInfo 指定的税率为 8%，则

    促销折扣率 = (AmountBeforeTax - 固定折扣) * (1 + 税率百分比)

    86.40 = (100 - 20) * 1.08
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price 0..1 float

必须提供 percentage、fixed_amount 或 fixed_price 中的一个。

如果指定了 AmountAfterTax 每晚房价，则此属性会将住宿一晚的价格（含税费及其他费用）设为指定的值。如果指定了 AmountBeforeTax，则无论是否指定了 AmountAfterTax，系统都会将住宿的税前价格设置为指定的值。假定其币种与每晚费率相同。

示例：

  • 如果单晚的 AmountBeforeTax 为 90，AmountAfterTax 为 100，fixed_price 为 80，则促销折扣率为 80。
  • 如果单晚的 AmountBeforeTax 为 100，fixed_amount 为 80，TaxFeeInfo 指定的税率为 8%，则

    促销折扣率 = 固定价格 *（1 + 税率）

    86.40 = 80 * 1.08
Promotions / HotelPromotions / Promotion / InventoryCount 0..1 InventoryCount 定义必须有多少个空房才能应用此促销活动的限制。折扣仅适用于符合约束条件的晚数。不允许与 fixed_amount 折扣搭配使用。请注意，可用客房数量是通过 OTA_HotelInvCountNotifRQ (InvCount) 或 OTA_HotelAvailNotifRQ (BookingLimit) 指定的。
Promotions / HotelPromotions / Promotion / InventoryCount / @min 0..1 integer 促销优惠应用于每晚房价所需的最低客房数。如果未指定，则表示无最小值。
Promotions / HotelPromotions / Promotion / InventoryCount / @max 0..1 integer 促销优惠适用于的客房数量上限。如果未指定，则表示无上限。
Promotions / HotelPromotions / Promotion / LengthOfStay 0..1 LengthOfStay 定义此促销活动适用的住宿晚数限制。如果住宿晚数超出最小值和上限，则不会应用促销优惠。
Promotions / HotelPromotions / Promotion / LengthOfStay / @min 0..1 integer 促销优惠的适用最短住宿晚数。如果未指定，则表示无最小值。
Promotions / HotelPromotions / Promotion / LengthOfStay / @max 0..1 integer 促销活动适用的住宿晚数上限。如果未指定，则表示无上限。
Promotions / HotelPromotions / Promotion / MembershipRateRule 0..1 MembershipRateRule

会员费率规则的容器，用于为关联的折扣触发特定的界面处理。

除非同时指定 <Discount>，否则不应指定此元素。
Promotions / HotelPromotions / Promotion / MembershipRateRule / @id 1 string

与会员回馈活动关联的 费率规则的 ID。
Promotions / HotelPromotions / Promotion / MinimumAmount 0..1 MinimumAmount 指定必须超过的每日房价总和（使用 AmountBeforeTax 或 AmountAfterTax 中的较大者），促销优惠才会应用。
Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount 1 integer 必须超过的值，系统才会应用促销优惠。
Promotions / HotelPromotions / Promotion / Occupancy 0..1 Occupancy 定义适用于此促销活动的入住人数限制。如果入住人数超出最低和最高限制，则不会应用促销优惠。
Promotions / HotelPromotions / Promotion / Occupancy / @min 0..1 integer 用户指定的入住人数必须至少达到此值，系统才会应用折扣。
Promotions / HotelPromotions / Promotion / Occupancy / @max 0..1 integer 用户指定的入住人数不得超过此值，否则系统将无法应用折扣。
Promotions / HotelPromotions / Promotion / RatePlans 0..1 RatePlans 包含适用于促销活动的费率方案列表的容器。 如果未指定 <RatePlans>，则促销优惠适用于所有费率方案。
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan 1..n RatePlan 指定费率方案。费率方案由套餐、房价和空房情况组合定义，如“交易（房源数据）”“OTA_HotelRateAmountNotifRQ”和“OTA_HotelAvailNotifRQ”消息中所定义，并由 PackageID 标识。
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id 1 string 费率方案的唯一标识符。此值会映射到 Transaction（房源数据）消息中的 <PackageData> 中的 PackageID 值，以及 <OTA_HotelRateAmountNotifRQ> 和 <OTA_HotelAvailNotifRQ> 消息中的 <StatusApplicationControl> 中的 RatePlanCode 属性。 允许的字符数上限为 50。
Promotions / HotelPromotions / Promotion / RoomTypes 0..1 RoomTypes 包含适用于促销活动的客房类型列表的容器。 促销活动会应用于指定的每个 <RoomType>。如果未指定 <RoomTypes>，则促销优惠适用于所有客房。
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType 1..n RoomType 指定房间类型。房间类型在交易（房源数据）消息的 <RoomData> 元素中定义，并使用其 <RoomID> 值进行引用。（OTA_HotelRateAmountNotifRQ 消息中的 InvTypeCode 属性也会引用其 <RoomID> 值。）
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id 1 string 房源（客房类型）的唯一标识符。此值在“交易（房源数据）”消息中映射到 <RoomID>。 允许的字符数上限为 50。
Promotions / HotelPromotions / Promotion / Stacking 0..1 Stacking 指定促销活动的组合方式。如果未指定，则假定“type”为 base。
Promotions / HotelPromotions / Promotion / Stacking / @type 1 enum

您可以为单一费率应用多项促销优惠，具体取决于此设置：

  • any：可与任何其他促销优惠（none 除外）搭配使用，但无法保证促销优惠的应用顺序。
  • base：系统会先选择最符合条件的 base 促销活动并应用该促销活动，然后再应用其他促销活动。此方法之前名为 base_only。
  • second：系统会在 base 促销优惠（如果适用）之后、any 促销优惠之前，选择并应用最优惠的符合条件的 second 促销优惠。
  • none：不能与其他促销活动搭配使用。

在允许的组合中，系统会对房价应用可提供最高折扣的一组促销活动。
Promotions / HotelPromotions / Promotion / StayDates 0..1 StayDates 一个或多个日期范围的容器，用于确定促销应用方式，例如适应季节性折扣。
Promotions / HotelPromotions / Promotion / StayDates / @application 1 enum

说明如何应用促销活动。

有效值包括：

  • all：如果行程中的所有日期与住宿日期重叠，则将促销优惠应用于行程中的每晚。
  • any：如果行程中的任何日期与住宿日期范围内的日期重叠，则将促销优惠应用于行程中的所有晚数。
  • overlap：仅将促销优惠应用于行程中与住宿日期范围重叠的晚数。

必须始终指定此属性。

  • 如果 <Discount> 指定了 percentage，并且 application 设置为 all 或 any，则折扣将以整次住宿费用的百分比形式应用。
  • 如果 <Discount> 指定了 percentage，并且 application 设为 overlap，则折扣将按重叠晚数的每晚房价的百分比应用。
  • <Discount> 指定 fixed_amount 且 application 设为 overlap 的组合无效。
  • <FreeNights> 支持所有 application 值。请注意，对于 overlap，系统仅会考虑重叠的住宿晚数来判断是否符合折扣条件。
Promotions / HotelPromotions / Promotion / StayDates / DateRange 1..99 DateRange

指定促销活动应用日期的日期范围。

也支持 YearlessDate 格式。

  • 如果 start 或 end 之一是无年份日期，则必须将这两个日期都填充为无年份日期。
  • 不含年份的日期范围不得跨越新年。请改为将该范围表示为两个相邻的日期范围。例如，{"12-29", "01-05"} 可以表示为 {"12-29", "12-31"} 和 {"01-01", "01-05"}。

如果您想设置 StayDates 范围，以允许在特定日期促销，则应将 start 日期设置为当前日期，不设置 end，以免促销活动过期。
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start 0..1 Date or YearlessDate 日期范围的开始日期（基于媒体资源所在的时区），包括该日期。此日期必须早于 end 日期或与之相同。如果未指定 start，则日期范围在开始日期方面实际上是无限的。

如果未提供 end 值，您应指定 start 值。
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end 0..1 Date or YearlessDate 日期范围的结束日期（以媒体资源所在的时区为准），含此日期。此日期必须与 start 日期相同或晚于该日期。如果未指定 end，则日期范围实际上从 start 日期起无限期。

如果未提供 start 值，您应指定 end 值。
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week 0..1 string

日期范围内允许的星期几。如果未指定，则日期范围内的所有日期均可。字符串中的每个字符都指定一天。例如，“MTWHF”表示日期范围内允许包含周一至周五。

有效字符包括：

  • M 表示周一
  • T 表示周二
  • W 表示周三
  • H 表示周四
  • F 表示周五
  • S 表示周六
  • U 表示周日

任何字符组合均有效。
Promotions / HotelPromotions / Promotion / UserCountries 0..1 UserCountries 用于列出符合促销条件的用户所在位置（国家/地区）的容器。如果指定了此属性，则只有列出的国家/地区中符合条件的用户才能享受折扣费率。如果未指定，则向任何国家/地区符合条件的用户提供折扣费率。
Promotions / HotelPromotions / Promotion / UserCountries / @type 0..1 enum UserCountries 规范的类型。

有效值为 include 和 exclude。

如果将 UserCountries type 设置为 include，则促销活动会应用于所列国家/地区的用户。

如果 UserCountries type 为 exclude，则促销活动适用于不在所列国家/地区的用户。

如果未设置 UserCountries type，系统会将其视为 include，并将促销应用于列出的国家/地区的用户。
Promotions / HotelPromotions / Promotion / UserCountries / Country 1..300 Country 指定用户需位于哪个国家/地区才能参与促销活动。
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code 1 string CLDR 国家/地区代码，例如 DE 或 FR。请注意，对于某些国家/地区，CLDR 国家/地区代码与两个字母的 ISO 国家/地区代码不同。此外，也不支持 CLDR 地区代码。

示例

对于每项媒体资源，您最多只能创建 500 项促销活动。如需从房源中移除促销活动，请参阅“删除一项促销活动”示例。

基本信息广告资源状态删除一项促销活动删除所有促销活动

以下示例展示了基本 Promotions 消息：

<?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">
      <BookingDates>
         <DateRange start="2020-07-01" end="2020-07-31" days_of_week="MTWHF"/>
         <DateRange start="2020-09-01" end="2020-09-30"/>
      </BookingDates>
      <BookingWindow min="7" max="330"/>
      <CheckinDates>
         <DateRange start="2020-10-01" end="2020-10-31" days_of_week="FSU"/>
      </CheckinDates>
      <CheckoutDates>
         <DateRange start="2020-10-08" end="2020-11-07" days_of_week="FSU"/>
      </CheckoutDates>
      <Devices>
        <Device type="mobile"/>
        <Device type="tablet"/>
      </Devices>
      <Discount percentage="20" applied_nights="2"/>
      <LengthOfStay min="2" max="14"/>
      <RatePlans>
         <RatePlan id="234"/>
         <RatePlan id="567"/>
      </RatePlans>
      <RoomTypes>
         <RoomType id="123"/>
         <RoomType id="456"/>
      </RoomTypes>
      <Stacking type="base"/>
      <UserCountries>
        <Country code="US"/>
        <Country code="GB"/>
      </UserCountries>
    </Promotion>
  </HotelPromotions>
</Promotions>

以下示例展示了如何在接近到货日期时创建超额库存折扣：

<?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">
      <BookingWindow max="7"/>
      <Discount percentage="10"/>
      <InventoryCount min="3"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

以下示例展示了如何删除房源的一项促销活动：

<?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" action="delete"/>
  </HotelPromotions>
</Promotions>

以下示例展示了如何删除房源的所有促销活动：

<?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" action="overlay"/>
</Promotions>


叠加所有促销活动3 种不同的堆叠类型无堆叠类型

以下示例展示了如何为房源叠加一个或多个新促销活动的 <HotelPromotions>。如果为 action="overlay"，系统会先删除所有已存储的促销活动，然后再存储当前消息中指定的促销活动：

<?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" action="overlay">
    <Promotion id="1">
      <BookingDates>
         <DateRange start="2020-09-01" end="2020-09-30"/>
      </BookingDates>
      <Discount percentage="10"/>
      <RoomTypes>
         <RoomType id="123"/>
         <RoomType id="456"/>
      </RoomTypes>
      <RatePlans>
         <RatePlan id="234"/>
         <RatePlan id="567"/>
      </RatePlans>
      <Stacking type="base"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

以下示例展示了将应用三种不同促销优惠（base、second、any）的情况。请注意，由于其他促销优惠提供的折扣更高，因此系统不会应用 none 促销优惠。如果原价为 100 美元，则折扣价为 72.90 美元。

<?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">
      <Discount percentage="10"/>
      <Stacking type="base"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="10"/>
      <Stacking type="second"/>
    </Promotion>
    <Promotion id="3">
      <Discount percentage="10"/>
      <Stacking type="any"/>
    </Promotion>
    <Promotion id="4">
      <Discount percentage="25"/>
      <Stacking type="none"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

以下示例展示了使用 none 促销代码的情况，因为其他促销代码组合提供的折扣较小。如果原价为 100 美元，则折扣价为 75 美元。

<?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">
      <Discount percentage="10"/>
      <Stacking type="base"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="10"/>
      <Stacking type="any"/>
    </Promotion>
    <Promotion id="3">
      <Discount percentage="25"/>
      <Stacking type="none"/>
    </Promotion>
  </HotelPromotions>
</Promotions>


预订期限时长边界预订日期日期时间边界不含年份的日期范围

以下示例展示了使用 BookingWindow 元素的情况，其中其开始和结束边界定义为 ISO 8601 时长类型。根据此预订时间范围限制，您必须在入住前一天的 18:00 当天或之前进行预订，并且必须在入住前 2 天的 12:00 当天或之后进行预订。

<?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">
      <BookingWindow min="P1DT6H" max="P2DT12H"/>
      <Discount percentage="20"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

以下示例展示了将 BookingDates 元素与 start 和 end 属性（类型为 DateTime）搭配使用的情况。根据此预订日期限制，预订时间必须在 2020 年 7 月 1 日 06:30 至 2020 年 7 月 2 日 18:45 之间。

<?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">
      <BookingDates>
         <DateRange start="2020-07-01T06:30:00" end="2020-07-02T18:45:00"/>
      </BookingDates>
      <Discount percentage="20"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

以下示例展示了 CheckInDates 元素包含 DateRanges 的情况，其中 start 和 end 字段不含年份。在此示例中，无论是哪一年，只要入住日期在 12 月 29 日至 1 月 2 日之间，即可享受此促销优惠。不含年份且跨越新年边界的日期范围无效，因此 DateRange 表示为两个相邻的日期范围。

<?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">
      <CheckInDates>
         <DateRange start="12-29" end="12-31"/>
         <DateRange start="01-01" end="01-02"/>
      </CheckInDates>
      <Discount percentage="20"/>
    </Promotion>
  </HotelPromotions>
</Promotions>


免费晚数折扣排名选择BestDailyDiscount

以下示例适用于指定的预订日期范围，每住满 4 晚，前 2 晚的房费可享 5 折优惠。对于 10 晚的行程，总共有 4 晚可享受 5 折优惠。

<?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">
      <BookingDates>
        <DateRange start="2022-01-01" end="2022-05-31"/>
      </BookingDates>
      <Discount>
        <FreeNights stay_nights="4" discount_nights="2" discount_percentage="50" night_selection="cheapest" repeats="true"/>
      </Discount>
    </Promotion>
  </HotelPromotions>
</Promotions>

在下例中，如果在指定的入住日期范围内入住 3 晚，则第 1 晚的费用可享受 5 折优惠。只有重叠的住宿晚数才会计入折扣条件。对于入住日期为 2022 年 1 月 1 日、退房日期为 2022 年 1 月 7 日的以下行程，符合条件的住宿晚数和折扣如下所示。

  • 2022-01-01（住宿）
  • 2022-01-02（住宿）
  • 2022-01-03
  • 2022 年 1 月 4 日（享受折扣）
  • 2022-01-05（住宿）
  • 2022-01-06（住宿）
<?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">
      <StayDates application="overlap">
        <DateRange start="2022-01-01" end="2022-01-02"/>
        <DateRange start="2022-01-04" end="2022-01-06"/>
      </StayDates>
      <Discount>
        <FreeNights stay_nights="3" discount_nights="1" discount_percentage="50" night_selection="last" repeats="true"/>
      </Discount>
    </Promotion>
  </HotelPromotions>
</Promotions>


以下示例提供了两个折扣，一个是八折，另一个是七五折。在评估期间，系统只会应用七五折折扣，因为它的排名较低。

<?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">
      <Discount percentage="15" rank="25"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="20" rank="50"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

以下示例通过应用堆叠的 BestDailyDiscount 和 Discount 来为两晚住宿提供折扣。

<?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="HotelID" action="overlay">
   <Promotion id="general">
     <BestDailyDiscount fixed_amount="20"/>
   </Promotion>
   <Promotion id="may">
     <BestDailyDiscount fixed_amount="50"/>
     <StayDates application="overlap">
        <DateRange start="2023-05-01" end="2023-05-31"/>
     </StayDates>
   </Promotion>
   <Promotion id="fiesta">
     <Discount fixed_amount_per_night="5"/>
     <Stacking type="any"/>
   </Promotion>
 </HotelPromotions>
</Promotions>

假设您要入住 2023 年 4 月 30 日至 2023 年 5 月 2 日这两晚。在计算时，系统会先找到可提供最优惠折扣的每日折扣组合。

对于第一晚，只有“一般”促销优惠符合条件，折扣金额固定为 20 美元。

对于第二晚，“可能”促销活动的折扣幅度高于“一般”折扣。因此，选择“可能”时，固定折扣金额为 50。

然后，对于此次住宿，“fiesta”促销折扣为每晚 5 美元，总计 10 美元。它可以与每日超值折扣组合叠加，因为“fiesta”的叠加类型已设为 any。如果将其设置为 base，则系统只会应用每日最佳折扣或“节日”折扣的组合。如需了解详情，请参阅 Stacking 的说明。

总体而言，住宿价格可享受 20 + 50 + 10 = 80 的固定金额折扣。

响应

语法

PromotionsResponse 消息使用以下语法：

<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="timestamp"
                    id="message_ID"
                    partner="partner_key">
  <!-- Either Success or Issues are populated. -->
  <Success/>
  <Issues>
    <Issue code="issue_code"
           status="issue_type">
      issue_description
    </Issue>
  </Issues>
</PromotionsResponse>

元素和属性

PromotionsResponse 消息包含以下元素和属性：

元素 / @Attribute 出现次数 类型 说明
PromotionsResponse 1 Complex element 根元素，用于指示收到的促销活动请求消息是否成功或存在问题。
PromotionsResponse / @timestamp 1 DateTime 此消息的创建日期和时间。
PromotionsResponse / @id 1 string 关联的促销信息中的唯一标识符。
PromotionsResponse / @partner 1 string 此消息对应的合作伙伴账号。
PromotionsResponse / Success 0..1 Success 表示促销活动消息已成功处理，没有警告、错误或失败。

每条消息中都包含 <Success> 或 <Issues>。
PromotionsResponse / Issues 0..1 Issues 用于容纳处理促销信息时遇到的一个或多个问题。

每条消息中都包含 <Success> 或 <Issues>。
PromotionsResponse / Issues / Issue 1..n Issue 处理促销活动消息时遇到的警告、错误或失败的说明。如需详细了解这些问题，请参阅 Feed 状态错误消息。
PromotionsResponse / Issues / Issue / @code 1 integer 问题的标识符。
PromotionsResponse / Issues / Issue / @status 1 enum

遇到的问题类型。

有效值为 warning、error 和 failure。

示例

成功问题

以下是对成功处理的促销活动消息的响应。

<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
                    id="12345678"
                    partner="partner_key">
  <Success/>
</PromotionsResponse>

以下是对因错误而未处理的促销活动消息的响应。

<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
                    id="12345678"
                    partner="partner_key">
  <Issues>
    <Issue code="1001" status="error">Example</Issue>
  </Issues>
</PromotionsResponse>