總覽
這個 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>
元素和屬性
促銷活動訊息包含下列元素和屬性:
元素 / @屬性 | 發生次數 | 類型 | 說明 |
---|---|---|---|
Promotions | 1 | Complex element | 促銷活動訊息的根元素。 |
Promotions / @partner | 1 | string | 這則訊息的合作夥伴帳戶。這個字串值為
「合作夥伴金鑰」列在
Hotel Center 的帳戶設定頁面。
如果您的後端
多個帳戶,這個值必須符合 |
Promotions / @id | 1 | string | 此要求訊息的專屬 ID。系統會傳回這個值 。允許的字元為 a-z、A-Z、0-9、_ (底線) 和 - (破折號)。 |
Promotions / @timestamp | 1 | DateTime | 這則訊息的建立日期和時間。 |
Promotions / HotelPromotions | 0..n | HotelPromotions | 房源的促銷活動。每項促銷活動都適用於單一 資源。 除非使用 |
Promotions / HotelPromotions / @hotel_id | 1 | string | 房源的專屬 ID。這個值必須符合
使用 指定飯店 ID
<listing> 元素中的 <id>
自動擷取廣告飯店 ID 也會列在 Hotel Center 中。 |
Promotions / HotelPromotions / @action | 0..1 | enum | 指定的值必須是
如未指定,則目前項目中指定的每個促銷活動。 訊息為以下其中一項:
|
Promotions / HotelPromotions / Promotion | 0..99 | Promotion | 房源的單一促銷活動。請注意,如果
如需使用超過 99 筆促銷活動,請聯絡 與您的客戶技術顧問 (TAM) 合作。 |
Promotions / HotelPromotions / Promotion / @id | 1 | string | 促銷活動的專屬 ID。每個 Pod 的 上限為 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 | 要套用折扣所需的住宿晚數。每項 折扣會套用至個別住宿晚數。 舉例來說,如果入住 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 | 是否可將折扣套用至多晚住宿
區隔如果設為 舉例來說,如果 |
Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | 為這項促銷活動指定排名,並選擇「排名選項」, 系統只會選取排名最低的促銷活動。值 必須介於 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 |
用來觸發特定 UI 的會員費率規則容器 來處理相關折扣。 除非必要,否則「請勿」指定這個元素
也指定 |
Promotions / HotelPromotions / Promotion / MembershipRateRule / @id | 1 | string | |
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 | 房價方案的專屬 ID。這個值對應至
<PackageData> 中的 PackageID 值
在「交易 (資源資料)」訊息和
RatePlanCode 屬性位於
兩者皆有 <StatusApplicationControl>
<OTA_HotelRateAmountNotifRQ> 和
<OTA_HotelAvailNotifRQ> 則訊息。
長度上限為 50 個半形字元。 |
Promotions / HotelPromotions / Promotion / RoomTypes | 0..1 | RoomTypes | 用來裝載促銷優惠的房型清單容器。
促銷活動適用於每個<RoomType>
。如未指定 <RoomTypes> ,
促銷活動適用於所有客房。 |
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType | 1..n | RoomType | 指定房間類型。房間類型的定義是在
中的 <RoomData> 元素
「交易 (資源資料)」訊息,以及
使用其 <RoomID> 值參照。(
<RoomID> 值也會由
OTA_HotelRateAmountNotifRQ 中的 InvTypeCode 屬性
messages.) |
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id | 1 | string | 商品目錄 (客房類型) 的專屬 ID。這個值對應
將條件設為「交易 (資源資料)」訊息中的 <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 規格的類型。
有效值為 如果使用者國家/地區 如果使用者國家/地區 如未設定 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 區碼。 |
範例
每個資源最多只能有 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>
疊加所有促銷活動
以下範例說明如何為屬性疊加 <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 種不同的堆疊類型
以下範例顯示 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 當天或之前預訂
抵達前一天,以及前 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-07-01 和 18:45 之間 (2020 年 7 月 2 日)。
<?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% 折扣。 指定的訂房日期範圍一到一晚的行程,總計 4 晚的優惠可享 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>
下一個範例提供 1 晚 50% 的折扣,而入住天數為 3 晚, 指定住宿日期範圍。只有重疊的住宿天數 也是符合折扣資格針對後續的行程安排報到 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>
排序選擇
以下範例提供兩項折扣,一項可享 8 折優惠和另一項折扣 即可享有 85 折優惠評估期間只會套用 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
以下範例透過申請來提供兩晚住宿折扣
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
然後在住宿地點「慶典」可享每晚 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
訊息包含下列元素和屬性:
元素 / @屬性 | 發生次數 | 類型 | 說明 |
---|---|---|---|
PromotionsResponse | 1 | Complex element | 表示接收端成功或問題的根元素 促銷活動要求訊息。 |
PromotionsResponse / @timestamp | 1 | DateTime | 這則訊息的建立日期和時間。 |
PromotionsResponse / @id | 1 | string | 相關促銷活動訊息的專屬 ID。 |
PromotionsResponse / @partner | 1 | string | 這則訊息的合作夥伴帳戶。 |
PromotionsResponse / Success | 0..1 | Success | 表示促銷活動訊息已成功處理
而不會出現警告、錯誤或失敗
|
PromotionsResponse / Issues | 0..1 | Issues | 用來存放處理
促銷訊息。
|
PromotionsResponse / Issues / Issue | 1..n | Issue | 出現警告、錯誤或失敗情形的說明 處理促銷活動訊息時,系統會自動進行處理。查看這些問題的詳細資料 英吋 動態饋給狀態錯誤訊息。 |
PromotionsResponse / Issues / Issue / @code | 1 | integer | 問題的 ID。 |
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>