促銷抵免額

總覽

這個 API 可讓您指定可能折扣。指定的促銷活動中，Google 會套用符合資格或最低價格的一組促銷活動。如果您正在尋找支援任意頻率調整，且在條件符合時調漲或調降價格的 API，請考慮使用費率調整 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 帳戶設定頁面中列出的「合作夥伴金鑰」值。

如果您的後端為多個帳戶提供動態饋給，這個值必須與同一個帳戶的 <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。這個值必須與飯店清單動態饋給中使用 <id> 元素指定的飯店 ID。<listing>Hotel Center 也會列出飯店 ID。
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，則沒有最小值。

有效的值類型如下：

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

有效的值類型如下：

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

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

促銷活動一律必須指定 <Discount> 或 <BestDailyDiscount>，因此如要建立僅套用 <Ceiling> 的促銷活動，您可選擇將 percentage 設為 0 的 <Discount>。

如果設定堆疊，含有 <Ceiling> 的多個促銷活動可能套用至單一住宿。每項促銷活動都會套用折扣，緊接著套用天花板。以下範例展示了每個上限對堆疊中的下一次促銷活動計算有何影響。

例子：

針對 AmountBeforeTax 為 100 且包含兩項促銷活動的一晚住宿計費：

  1. 堆疊類型為 base、fixed_amount 為 25，且天花板 amount_per_night 為 60 的促銷活動
  2. 堆疊類型為 second、fixed_amount 為 25，且天花板 amount_per_night 為 90 的促銷活動

計算順序如下：

  1. 系統會先套用 base 促銷活動，並將 AmountBeforeTax 的折扣降至 75，但之後上限則會將折扣降低為 60。
  2. second 促銷折扣 AmountBeforeTax，從 60 降至 35。低於 90 的天花板，因此不會套用第二個天花板。最終匯率為 35。

60 是比整體天花板較嚴格的上限，因為這個上限只用於本身的促銷活動，而且沒有橫跨整個促銷活動堆疊的單天上限。
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night 1 float

套用折扣後，每晚費率的最高金額。

如果同時指定 <Floor> 元素，這個值必須設為大於或等於 <Floor> 中的 amount_per_night 屬性的值。

如果使用 AmountAfterTax 計入每晚房價的稅金和費用，則 amount_per_night 會扣除上述稅金。不過，使用 TaxFeeInfo 指定的價格除外。
Promotions / HotelPromotions / Promotion / Floor 0..1 Floor

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

促銷活動一律必須指定 <Discount> 或 <BestDailyDiscount>，因此如要建立僅套用 <Floor> 的促銷活動，您可選擇將 percentage 設為 0 的 <Discount>。

<Floor> 邏輯仍適用於 <FreeNights> 的折扣，即使免費夜間享有 100% 折扣也一樣。

如果設定堆疊，含有 <Floor> 的多個促銷活動可能套用至單一住宿。每項促銷活動都會套用折扣，緊接在最低限額後立即套用。以下範例顯示每個樓層對堆疊中的下一次促銷活動計算方式有何影響。

例子：

針對 AmountBeforeTax 為 100 且包含兩項促銷活動的一晚住宿計費：

  1. 堆疊類型為 base、fixed_amount 為 25 且樓層 amount_per_night 為 90 的促銷活動
  2. 堆疊類型為 second、fixed_amount 為 25，且樓層 amount_per_night 為 60

計算順序如下：

  1. 系統會先套用 base 促銷活動，並將 AmountBeforeTax 的折扣設為 75，但底價會調高至 90。
  2. second 促銷折扣 AmountBeforeTax，從 90 降至 65。高度高於 60 樓，因此不會套用第二層樓。最終匯率為 65。

這個 90 代表總樓面的樓層越嚴格，與本身的促銷活動無關，而且不能涵蓋整個促銷活動堆疊的單一樓層。
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night 1 float

套用折扣後，每晚費率可設為的最低金額。

如果同時指定 <Ceiling> 元素，該元素必須設為小於或等於 <Ceiling> 中 amount_per_night 屬性的值。

如果使用 AmountAfterTax 計入每晚房價的稅金和費用，則 amount_per_night 會扣除上述稅金。不過，使用 TaxFeeInfo 指定的價格除外。
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 總和)。假設使用的是與每晚費率相同的貨幣。如果這個值大於每晚費率的總和，產生的值會是零。

示例：

  • 如果我們採用的是 1 晚的住宿價格，其中 AmountBeforeTax 為 90，AmountAfterTax 為 100，fixed_amount 為 20，那麼

    促銷費率 = AmountAfterTax - 固定折扣

    80.00 = 100 - 20

  • 如果我們採用 1 晚的住宿價格，其中 AmountBeforeTax 為 100，fixed_amount 為 20，而 TaxFeeInfo 指定 8% 的稅金，那麼：

    促銷費率 = (AmountBeforeTax - 固定折扣) * (1 + 百分比稅金)

    86.40 = (100 - 20) * 1.08

  • 如果我們採用 1 晚的住宿價格，其中 AmountBeforeTax 為 50，fixed_amount 為 60，且 TaxFeeInfo 指定 10 稅金，那麼

    促銷費率 = (AmountBeforeTax - 固定折扣) * 稅金

    10.00 = 0 + 10

  • 如果我們的價格是為 3 晚住宿，其中 AmountAfterTax 值為 100、110 和 120，而 fixed_amount 為 150，則

    促銷率 = sum(AmountAfterTax) - (固定折扣)

    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，則

    促銷率 = sum(AmountBeforeTax - 固定金額折扣)

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

  • 如果我們的價格是為 3 晚住宿，其中 AmountAfterTax 值為 10、50 和 100，而 fixed_amount_per_night 為 20，則

    促銷率 = sum(AmountAfterTax - 固定金額折扣)

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

必須提供 percentage、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

要套用折扣的住宿天數。每項折扣會套用至不同的住宿住宿時段。

舉例來說，假設在 stay_nights 為 4 (且 repeats 為 true) 入住 10 晚，則有兩個住宿晚區隔：第 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 時，如果 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 不同，後者會將折扣套用至整個入住。

每項房源可能都有一組「每日最佳」促銷活動。也就是說，針對每晚的住宿地點，商家可以選取且能套用最短的「每日最佳」促銷活動。

BestDailyDiscount 無法指定 Stacking。為每晚帶來最低折扣的「最佳每日」折扣會合併，並視為單一入住折扣 (即 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 固定金額 (如未指定 AmountBeforeTax 每晚房價 (如未指定) AmountAfterTax)。假設使用的是與每晚費率相同的貨幣。如果這個值大於每晚費率的總和，產生的值會是零。

示例：

  • 如果單晚的 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 指定促銷活動的組合方式。如未指定，系統會假設「type」為 base。
Promotions / HotelPromotions / Promotion / Stacking / @type 1 enum

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

  • any：可與任何其他促銷活動合併使用 (none 除外)，但不保證應套用促銷活動的順序。
  • base：系統會先選取並套用最適合的base促銷活動，優先套用於其他促銷活動。先前的名稱是 base_only。
  • second：在 base 促銷活動 (如適用) 結束後和 any 促銷活動之前，系統會選取並套用最適合的 second 促銷活動。
  • none：無法與其他促銷活動合併使用。

在允許的組合中，最終產生最多折扣的促銷活動組合會套用至這項費率。
Promotions / HotelPromotions / Promotion / StayDates 0..1 StayDates 存放一或多個日期範圍的容器，用來決定促銷活動的套用方式，例如配合季節性折扣。
Promotions / HotelPromotions / Promotion / StayDates / @application 1 enum

說明如何套用促銷活動。

以下為有效值：

  • all：如果行程中的「所有」日期與住宿日期重疊，則適用於行程中的每晚。
  • any：如果行程中的任何日期與住宿日期範圍的日期重疊，就將促銷活動套用至行程中的所有日期。
  • overlap：僅適用於行程中日期與住宿日期範圍日期重疊的住宿夜數。

必須指定這個屬性。

  • 如果 <Discount> 指定 percentage 且 application 設為 all 或 any，折扣就會以完整入住的百分比套用。
  • 如果 <Discount> 指定 percentage 並將 application 設為 overlap，則系統會針對重疊住宿夜晚的每晚費率套用折扣。
  • <Discount> 指定 fixed_amount 和 application 設為 overlap 是無效的組合。
  • <FreeNights> 支援所有 application 值。請注意，如果是 overlap，系統只會將重疊的住宿夜數視為折扣要求。
Promotions / HotelPromotions / Promotion / StayDates / DateRange 1..99 DateRange

指定促銷活動生效日期的日期範圍。

系統也支援 YearlessDate 格式。

  • 如果 start 或 end 中有任何日期為無年日期，就必須將兩者填入無年日期。
  • 未設定年度的日期範圍不得在新年前後。而是將範圍表示為兩個相鄰的日期範圍。舉例來說，{"12-29", "01-05"} 可用 {"12-29", "12-31"} 和 {"01-01", "01-05"} 表示。
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>

Booking Dates DateTime Bounds (預訂日期日期時間範圍)

以下範例顯示 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 折扣

以下範例針對指定的預訂日期範圍，針對入住日期範圍的每 4 晚提供 5 晚的折扣。如果是 10 晚的行程，總共四晚可享 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% 的折扣。只有重疊的入住天數才會計入折扣。對於下列行程在 2022 年 1 月 1 日入住和 2022 年 1 月 7 日退房的行程，適用的住宿夜數和折扣如下：

  • 2022 年 1 月 1 日 (入住)
  • 2022 年 1 月 2 日 (入住)
  • 2022-01-03
  • 2022 年 1 月 4 日 (折扣價)
  • 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>


排序選擇

以下範例提供兩項折扣，一項分別是 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>

最佳每日折扣

以下範例會套用與 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 訊息包含下列元素和屬性：

元素 / @Attribute 發生次數 類型 說明
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>