總覽
這個 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。這個值必須與飯店清單動態饋給中
<listing> 元素中的 <id> 指定的飯店 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。允許的字元數上限為 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 ,則每個選定夜晚適用 50% 折扣。 |
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 |
與會員方案相關聯的 費率規範 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 | 房價方案的專屬 ID。這個值會對應至「交易 (資源資料)」訊息中 <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 | 商品目錄 (客房類型) 的專屬 ID。這個值會對應至交易 (資源資料) 訊息中的 <RoomID> 。長度上限為 50 個半形字元。 |
Promotions / HotelPromotions / Promotion / Stacking | 0..1 | Stacking | 指定促銷活動的合併方式。如未指定,系統會假設「類型」為 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 規格的類型。 有效值為 如果使用者國家/地區 如果使用者國家/地區 如未設定使用者國家/地區 |
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 Duration 類型定義的開始和結束邊界搭配使用。這類預訂回溯期限制需要在抵達前一天 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 日 6:30 至 2020 年 7 月 20 日 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-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 折優惠,另一種則提供 15% 折扣。在評估期間,由於排名較低,系統只會套用 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 日入住兩晚。在計算時,系統會先找出能帶來最高折扣的最佳每日折扣組合。
針對第一晚,「一般」促銷活動是唯一符合資格的金額,且固定折扣為 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>