概览
您可以使用此 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, 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" 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,则此值需要与同一帐号的 |
Promotions / @id | 1 | string | 此请求消息的唯一标识符。该值在响应消息中返回。允许使用的字符包括 a-z、A-Z、0-9、_(下划线)和 -(短划线)。 |
Promotions / @timestamp | 1 | DateTime | 此消息的创建日期和时间。 |
Promotions / HotelPromotions | 0..n | HotelPromotions | 房源的促销信息。每个促销活动都适用于单个房源。 除非使用 |
Promotions / HotelPromotions / @hotel_id | 1 | string | 房源的唯一标识符。此值必须与酒店列表 Feed 的 <listing> 元素中的
<id> 指定的酒店 ID 一致。Hotel Center 中也会列出酒店 ID。 |
Promotions / HotelPromotions / @action | 0..1 | enum | 如果指定,则值必须为 如果未指定,则当前消息中指定的每个促销活动为以下任一项:
|
Promotions / HotelPromotions / Promotion | 0..99 | Promotion | 一项房源的促销活动。请注意,如果未指定 如果您需要使用超过 99 个促销活动,请与您的技术支持客户经理 (TAM) 联系。 |
Promotions / HotelPromotions / Promotion / @id | 1 | string | 促销活动的唯一标识符。允许的最大字符数为 40。允许使用的字符包括 a-z、A-Z、0-9、_(下划线)、-(短划线)和 . (英文句点)。 |
Promotions /HotelPromotions / Promotion / @action | 0..1 | enum | 如果指定,则值必须为 如果指定了 |
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 | 范围的开始日期或日期时间(基于属性的时区),包括此日期或日期时间。
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end | 0..1 | Date或 DateTime | 范围的结束日期或日期时间(基于媒体资源的时区),包括此日期或日期时间。
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week | 0..1 | string | 允许出现在日期范围内的星期几。如果未指定,则日期范围允许所有日期。字符串中的每个字符都表示日期。例如,“MTWHF”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
Promotions / HotelPromotions / Promotion / BookingWindow | 0..1 | BookingWindow | 指定相对于入住日期(以酒店所在的时区)为准的预订时间段。例如,预订期限可设置为入住前至少 7 天,但不超过 180 天。 |
Promotions / HotelPromotions / Promotion / BookingWindow / @min | 0..1 | integer or duration | 入住前必须至少预订入住前的最短时长,才能应用促销优惠。如果未指定或其值为 0 ,则没有最小值。
有效的值类型包括:
|
Promotions / HotelPromotions / Promotion / BookingWindow / @max | 0..1 | integer or duration | 您入住前必须提前最晚入住的天数才可享受促销优惠。如果未指定此值或其值为 0 ,则没有最大值。
有效的值类型包括:
|
Promotions / HotelPromotions / Promotion / Ceiling | 0..1 | Ceiling |
定义在应用促销优惠后可设置的费率最大值的限制。 促销必须始终指定 如果配置了堆叠,那么多项具有 例如: 当
计算顺序如下:
60 是更严格的整体上限,这无关紧要,因为它仅对其自身的促销活动有效,并且不存在跨整个促销活动堆栈的单一上限。 |
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night | 1 | float |
应用折扣后,每晚费率可设置的最高金额。 如果还指定了 如果使用 |
Promotions / HotelPromotions / Promotion / Floor | 0..1 | Floor |
定义在应用促销优惠后,可设置费率的最小值的限制。 促销必须始终指定
如果配置了堆叠,那么多项具有 例如: 当
计算顺序如下:
90 是更严格的总体底价没有关系,因为它仅适用于自己的促销活动,并且没有一个底价可覆盖整个促销活动堆栈。 |
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night | 1 | float |
应用折扣后,每晚费率可设置的最低金额。 如果还指定了 如果使用 |
Promotions / HotelPromotions / Promotion / CheckinDates | 0..1 | CheckinDates | 一个或多个日期范围的容器,用于指定入住时间才能应用促销优惠。 |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange | 1..20 | DateRange | 一个日期范围,用于指定必须在什么时间入住才能应用促销优惠。如果您要删除一个或多个促销活动,则无需添加此元素。 还支持 YearlessDate 格式。
|
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”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
Promotions / HotelPromotions / Promotion / CheckoutDates | 0..1 | CheckoutDates | 一个或多个日期范围的容器,用于指定必须在什么时间退房才能应用促销优惠。 |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange | 1..20 | DateRange | 一个日期范围,用于指定必须在什么时间退房才能应用促销优惠。如果您要删除一个或多个促销活动,则无需添加此元素。 还支持 YearlessDate 格式。
|
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”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
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 | 必须且只能指定 指定要应用于此促销活动的折扣。 |
Promotions / HotelPromotions / Promotion / Discount / @percentage | 0..1 | float | 必须提供 一个介于 0-100 之间的十进制值,用于指定百分比折扣。
它应用于 示例:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount | 0..1 | float | 必须提供 从 示例:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night | 0..1 | float | 必须提供 应用于每个 示例:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price | 0..1 | float | 必须提供 如果指定了 如果 示例:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night | 0..1 | float | 必须提供 如果指定了 如果 如果指定了 示例:
|
Promotions / HotelPromotions / Promotion / Discount / @applied_nights | 0..1 | integer | 此方法只能与 应用折扣的晚数,从价格最低的房间开始。必须是 1 到 99 之间的整数。如果未指定,折扣将应用于所有夜晚。 |
Promotions / HotelPromotions / Promotion / Discount / FreeNights | 0..1 | FreeNights | 指定在满足最短入住天数要求时,为入住的某些晚数指定折扣。如果使用了父级 Discount 元素,则不允许使用相关属性。 |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights | 1 | integer | 应用折扣所需的住宿晚数。每个折扣都会应用于单独的住宿晚数细分。 例如,对于 |
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 | 折扣是否可以应用于多个住宿晚数细分。如果为 例如,如果 |
Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | 为该促销活动指定排名,并选择按排名选择促销活动,即只有排名最低的促销活动才会被选中应用。值必须介于 1 到 99 之间(含 1 和 99)。如果多个促销活动的排名相同,系统会任意选择并应用其中一个促销活动。 |
Promotions / HotelPromotions / Promotion / BestDailyDiscount | 1 | Discount | 必须且只能指定 指定可应用于住宿一晚的每日折扣。这与 每个房源可能有一组被视为“每日最佳”的促销活动。这意味着,对于每晚住宿,系统会选择单个符合条件且能为该夜晚产生最大折扣的“每日最佳”促销活动,您可以应用该促销活动。
此类折扣可指定 |
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage | 0..1 | float | 必须提供 一个介于 0-100 之间的十进制值,用于指定百分比折扣。
它应用于 示例:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount | 0..1 | float | 必须提供 从单个 示例:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price | 0..1 | float | 必须提供 如果指定了 示例:
|
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 |
用于触发对关联折扣的特定界面处理的会员费率规则的容器。 除非同时指定了 |
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 | 费率方案的唯一标识符。此值会映射到交易(房源数据)消息中的 <PackageData> 中的 PackageID 值,以及 <OTA_HotelRateAmountNotifRQ> 和 <OTA_HotelAvailNotifRQ> 消息中 <StatusApplicationControl> 的 RatePlanCode 属性中的 PackageID 值。
允许的最大字符数为 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 | 根据此设置,可以将多个促销活动应用于单个费率:
在允许的组合中,折扣最多的那组促销活动会应用于费率。 |
Promotions / HotelPromotions / Promotion / StayDates | 0..1 | StayDates | 一个或多个日期范围的容器,用于确定如何应用促销活动,例如适应季节性折扣。 |
Promotions / HotelPromotions / Promotion / StayDates / @application | 1 | enum | 说明应如何应用促销优惠。 有效值包括:
必须始终指定此属性。
|
Promotions / HotelPromotions / Promotion / StayDates / DateRange | 1..99 | DateRange | 用于指定促销活动应用日期的日期范围。 还支持 YearlessDate 格式。
|
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start | 0..1 | Date or YearlessDate | 日期范围的开始日期(基于房源的时区)。此日期必须早于 end 日期或与其相同。如果未指定 start ,就开始日期而言,日期范围实际上没有限制。 |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end | 0..1 | Date or YearlessDate | 日期范围的结束日期(基于媒体资源的时区,含此日期)。此日期必须与 start 日期相同或更晚。如果未指定 end ,就结束日期而言,日期范围实际上没有限制。 |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week | 0..1 | string | 允许出现在日期范围内的星期几。如果未指定,则日期范围允许所有日期。字符串中的每个字符都表示日期。例如,“MTWHF”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
Promotions / HotelPromotions / Promotion / UserCountries | 0..1 | UserCountries | 用于列出符合促销条件的用户地理位置(国家/地区)的容器。如果已指定,则只有所列国家/地区中符合条件的用户可享受折扣价。如果未指定,则系统会为任何国家/地区符合条件的用户提供折扣费率。 |
Promotions / HotelPromotions / Promotion / UserCountries / @type | 0..1 | enum | UserCountry 规范的类型。
有效值为 如果 UserCountry 如果 Usercountry 的 如果未设置 User countries |
Promotions / HotelPromotions / Promotion / UserCountries / Country | 1..300 | Country | 指定一个国家/地区,在该国家/地区,用户符合促销条件。 |
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code | 1 | string | CLDR 国家/地区代码,例如 DE 或 FR 。请注意,对于某些国家/地区,CLDR 国家/地区代码与由 2 个字母组成的 ISO 国家/地区代码不同。此外,CLDR 地区代码也不受支持。 |
示例
基本消息
以下示例展示了基本的 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>
叠加所有促销活动
以下示例展示了如何将 <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>
3 种不同的堆叠类型
以下示例展示了应用三个不同促销活动(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 或之后预订,以及入住前第二天的 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>
FreeNights 折扣
以下示例将在指定预订日期范围内每入住四晚,享受两晚 50% 的折扣。对于十晚的行程,总共四晚可享受 50% 的折扣。
<?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>
下一个示例会在指定住宿日期范围内每入住三晚,享受一晚 50% 的折扣。只有重叠的住宿晚数才有资格享受折扣。对于以下行程,入住日期为 2022 年 1 月 1 日,退房日期为 2022 年 1 月 7 日,符合条件的住宿晚数和折扣适用情况如下。
- 2022 年 1 月 1 日(住宿)
- 2022 年 1 月 2 日(住宿)
- 2022-01-03
- 2022-01-04(折扣)
- 2022 年 1 月 5 日(住宿)
- 2022 年 1 月 6 日(住宿)
<?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>
选择排名
以下示例提供了两种折扣,一种是八折优惠,另一种是八五折优惠。在评估期间,由于排名较低,系统仅会应用 15% 的折扣。
<?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
堆叠的 BestDailyDiscount
来折扣两晚住宿。
<?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 日住宿两晚 在计算时,系统会先找出能产生最大折扣的最佳每日折扣组合。
第 1 晚,“常规”促销活动是唯一符合条件的金额,固定折扣为 20。
对于第二晚,“可能”促销活动提供的折扣比“一般”折扣的折扣力度更大。因此,如果选择“可以”,则固定折扣金额为 50。
如果是入住,则可获享“嘉年华”促销折扣为每晚 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 | 表示促销消息已成功处理,没有出现警告、错误或失败。
每条消息中是否存在 |
PromotionsResponse / Issues | 0..1 | Issues | 处理“推广”消息时遇到的一个或多个问题的容器。
每条消息中是否存在 |
PromotionsResponse / Issues / Issue | 1..n | Issue | 处理促销消息时遇到的警告、错误或失败的说明。如需详细了解这些问题,请参阅 Feed 状态错误消息。 |
PromotionsResponse / Issues / Issue / @code | 1 | integer | 问题的标识符。 |
PromotionsResponse / Issues / Issue / @status | 1 | enum | 遇到的问题类型。 有效值为 |
示例
成功
以下是对已成功处理的促销消息的响应。
<?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>