促銷

總覽

這個 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 中 帳戶設定頁面列出的「合作夥伴鍵」值。

如果您的後端為多個帳戶提供動態饋給，這個值必須符合 <OTA_HotelRateAmountNotifRQ> 的 <RequestorID> 元素中指定的 ID 屬性值，以及同一帳戶的 <OTA_HotelAvailNotifRQ> 訊息。
Promotions / @id 1 string 此要求訊息的專屬 ID。這個值會在回應訊息中傳回。允許的字元為 a-z、A-Z、0-9、_ (底線) 和 - (破折號)。
Promotions / @timestamp 1 DateTime 這則訊息的建立日期和時間。
Promotions / HotelPromotions 0..n HotelPromotions

房源的促銷活動。每個促銷活動都適用於單一資源。

除非使用 <Stacking>，否則當多項促銷活動符合資格時，系統會對預訂套用折扣最多的促銷活動。
Promotions / HotelPromotions / @hotel_id 1 string 房源的專屬 ID。這個值必須與飯店清單動態饋給中 <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 促銷活動的專屬 ID。允許的字元數上限為 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，則沒有最小值。

有效的值類型包括：

  • Integer：入住日期前的天數。舉例來說，30 表示促銷活動僅適用於入住日期至少 30 天前的預訂行程。
  • ISO 8601 時間長度 (天、小時和分鐘)：入住日期前的天數 (可視需要加上小時/分鐘)。舉例來說，P30D 表示促銷活動僅適用於入住日期至少 30 天前的預訂。如果值為 P30DT6H，則必須在抵達日前 30 天的 18:00 當天或之前預訂。
Promotions / HotelPromotions / Promotion / BookingWindow / @max 0..1 integer or duration 你必須在入住前最多天數入住才能套用促銷優惠。如未指定，或值為 0，則沒有上限。

有效的值類型包括：

  • Integer：入住日期前的天數。舉例來說，如果值為 30，表示促銷活動僅適用於入住日期最晚 30 天的預訂。
  • ISO 8601 時間長度 (天、小時和分鐘)：入住日期前的天數 (可視需要加上小時/分鐘)。舉例來說，P30D 表示促銷活動僅適用於入住日期前 30 天的預訂。如果值為 P30DT6H，則必須在抵達日前 30 天的 18:00 當天或之後預訂。
Promotions / HotelPromotions / Promotion / Ceiling 0..1 Ceiling

定義套用促銷活動後可設定費率的最大值限制。

促銷活動一律必須指定 <Discount> 或 <BestDailyDiscount>，因此如要建立僅適用於<Ceiling>的促銷活動，其中一種做法是將 <Discount> 設為 percentage 和 0。

如果設定堆疊，則含有 <Ceiling> 的多項促銷活動可能會套用至單一住宿活動。每項促銷活動都會套用折扣，隨後顯示上限。以下範例說明瞭各天花板如何影響堆疊中下次促銷活動的比例。

範例：

為 AmountBeforeTax 為 100 且提供 1 晚的住宿價格，且有兩個促銷活動：

  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 指定的稅金和費用。
Promotions / HotelPromotions / Promotion / Floor 0..1 Floor

定義套用促銷活動後可設定費率的最小值限制。

促銷活動一律必須指定 <Discount> 或 <BestDailyDiscount>，因此如要建立僅適用於<Floor>的促銷活動，其中一種做法是將 <Discount> 設為 percentage 和 0。

<Floor> 邏輯仍適用於 <FreeNights> 折扣，即使免費晚上套用了 100% 折扣也一樣。

如果設定堆疊，則含有 <Floor> 的多項促銷活動可能會套用至單一住宿活動。每項促銷活動都會套用折扣，並在後方加上底價。以下範例說明每個樓層如何影響堆疊中下次的促銷活動計算方式。

範例：

為 AmountBeforeTax 為 100 且提供 1 晚的住宿價格，且有兩個促銷活動：

  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 指定的稅金和費用。
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、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 / @fixed_amount 0..1 float

至少必須有一個 percentage、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night。

要從 AmountAfterTax 每晚房價總和減去的固定金額 (如未指定 AmountAfterTax，則為 AmountBeforeTax 的每晚房價總和)。系統會假設其幣別與每晚房價相同。如果這個值大於每晚房價的總和，結果值為 0。

例：

  • 如果價格為 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，則

    促銷費率 = 總和(AmountAfterTax) - (固定折扣)

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

至少必須有一個 percentage、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，則

    促銷費率 = 加總(AmountBeforeTax - 固定金額折扣)

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

  • 假設價格為 3 晚，且 AmountAfterTax 值為 10、50 和 100，而 fixed_amount_per_night 為 20，則

    促銷費率 = 加總(AmountAfterTax - 固定金額折扣)

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

至少必須有一個 percentage、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、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，則每個選定夜晚適用 50% 折扣。
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 指定。系統會將每晚最低折扣的「每日最佳」折扣合併為單一入住折扣 (即 Discount)，堆疊類型則設為 base。這項合併折扣會與其他符合資格的 <折扣> 促銷活動相互比較，並與其他符合資格的 <折扣> 促銷活動合併比較，以找出可提供最低折扣的其中一項或組合。系統會選擇 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 的每晚房價)。系統會假設其幣別與每晚房價相同。如果這個值大於每晚房價的總和，結果值為 0。

例：

  • 如果一晚的 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

會員費率規則的容器，用於觸發相關折扣的特定 UI 處理方式。

除非一併指定 <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 房價方案的專屬 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

視這項設定而定，你可以為單一費率套用多項促銷活動：

  • any：可與任何其他促銷活動合併使用 (none 除外)，但不保證套用促銷活動的順序。
  • base：系統會先選取並套用最適合的 base 促銷活動，然後優先套用。原名為 base_only。
  • second：選出最適合的 second 促銷活動，並在 base 促銷優惠 (如適用) 後及 any前套用。
  • 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"} 表示。
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" 能指定日期範圍內允許星期幾。

有效的字元包括：

  • M (週一)
  • T (星期二)
  • W 代表星期三
  • H 代表星期四
  • F 代表星期五
  • S (星期六)
  • U 代表週日

任何字元組合都有效。
Promotions / HotelPromotions / Promotion / UserCountries 0..1 UserCountries 用來列出符合促銷活動資格的使用者位置 (國家/地區) 的容器。指定時，只有所列國家/地區內符合資格的使用者才能享有折扣費率。如未指定，任何國家/地區的合格使用者均適用折扣費率。
Promotions / HotelPromotions / Promotion / UserCountries / @type 0..1 enum UserCountry 規格的類型。

有效值為 include 和 exclude。

如果使用者國家/地區 type 設為 include，促銷活動就會適用於下列國家/地區的使用者。

如果使用者國家/地區 type 為 exclude，這項促銷活動適用於下列國家/地區以外的使用者。

如未設定使用者國家/地區 type，系統會將其視為 include，並套用至下列國家/地區的使用者。
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 表示促銷活動訊息已成功處理，不會出現警告、錯誤或失敗。

每則訊息中都含有 <Success> 或 <Issues>，
PromotionsResponse / Issues 0..1 Issues 用來存放處理促銷活動訊息時遇到的一或多個問題的容器。

每則訊息中都含有 <Success> 或 <Issues>，
PromotionsResponse / Issues / Issue 1..n Issue 處理促銷活動訊息時出現的警告、錯誤或失敗說明。如要進一步瞭解這些問題，請參閱動態饋給狀態錯誤訊息。
PromotionsResponse / Issues / Issue / @code 1 integer 問題的 ID。
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>