促銷內容

總覽

您可以使用這個 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, percentage_of_base, 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" percentage_of_base="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> 和 <OTA_HotelAvailNotifRQ> 訊息中 <RequestorID> 元素的 ID 屬性值相符。
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，則沒有最小值。

有效的值類型包括：

  • 整數：入住日期前的天數。舉例來說，30 值表示促銷活動僅適用於入住日期前至少 30 天的預訂。
  • ISO 8601 期間 (天數、時數和分鐘數)：入住日期前的天數 (和選填的時數/分鐘數)。舉例來說，P30D 表示促銷活動僅適用於入住日期前至少 30 天的預訂。P30DT6H 值為 1，表示必須在抵達前 30 天的 18:00 前預訂。
Promotions / HotelPromotions / Promotion / BookingWindow / @max 0..1 integer or duration 促銷活動適用於入住前幾天預訂的訂單，天數上限為 330 天。如未指定，或值為 0，則沒有上限。

有效的值類型包括：

  • 整數：入住日期前的天數。舉例來說，值為 30 表示促銷活動僅適用於入住日期前最多 30 天的預訂。
  • ISO 8601 期間 (天數、時數和分鐘數)：入住日期前的天數 (和選填的時數/分鐘數)。舉例來說，P30D 值表示促銷活動僅適用於入住日期前最多 30 天的預訂。如要取得 P30DT6H 值，請在抵達前 30 天當天或之後預訂，且預訂時間須為 18:00 後。
Promotions / HotelPromotions / Promotion / Ceiling 0..1 Ceiling

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

促銷活動一律須指定 <Discount> 或 <BestDailyDiscount>，因此如要建立只套用 <Ceiling> 的促銷活動，其中一個做法是將 <Discount> 設為 percentage，並將 0 設為 <Discount>。

如果已設定堆疊，則多個促銷活動可能會套用至單一住宿。<Ceiling>每個促銷活動都會套用折扣，然後立即套用上限。以下範例說明每個上限如何影響堆疊中的下一個促銷活動計算。

範例：

為住宿 1 晚的房價定價，其中 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> 的促銷活動，其中一個做法是將 <Discount> 設為 percentage，並將 0 設為 <Discount>。

<Floor> 邏輯仍適用於<FreeNights>折扣，即使免費住宿已套用 100% 折扣。

如果已設定堆疊，則多個促銷活動可能會套用至單一住宿。<Floor>每個促銷活動都會套用折扣，然後立即套用底價。以下範例說明每個底價如何影響堆疊中下一個促銷活動的計算。

範例：

為住宿 1 晚的房價定價，其中 AmountBeforeTax 為 100，且有兩項促銷活動：

  1. 堆疊類型為 base 的促銷活動，fixed_amount 為 25，底價為 amount_per_night 90
  2. 促銷活動，堆疊類型為 second， fixed_amount 為 25，底價為 60 amount_per_night

計算順序如下：

  1. 系統會先套用 base 促銷活動，將 AmountBeforeTax 折扣至 75，但隨後底價會將價格調高至 90。
  2. second促銷活動將 AmountBeforeTax從 90 分調降至 65 分。這高於 60 的下限，因此不會套用第二層。最終費率為 65。

90 是較嚴格的整體底價，但這項底價只適用於該促銷活動，且整個促銷活動堆疊中無法有單一底價，因此 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、percentage_of_base、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 / @percentage_of_base 0..1 float

必須提供 percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 其中之一。

介於 0 到 100 之間的小數值，指定基本折扣的百分比。與 percentage 類似，這項屬性會套用至 AmountAfterTax (或未指定 AmountAfterTax 時的 AmountBeforeTax)。

與 percentage 不同，無論先前已依序套用哪些促銷活動，這項折扣一律會以基本費率的百分比計算。

範例：

  • 假設我們有兩項促銷活動，依序套用至一晚的住宿，價格為 100。第一個是 10% 的一般百分比折扣，第二個是 10% 的基本折扣百分比。因此折扣率為 80，因為兩項促銷活動都提供 10 元折扣。請注意，如果第二項促銷活動也提供一般百分比折扣，則折扣率為 81，因為第二項促銷活動會從 90 元中扣除 10%。
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount 0..1 float

必須提供 percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 其中之一。

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

範例：

  • 假設我們為入住一晚的住宿定價，其中 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、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price 或 fixed_price_per_night 其中之一。

套用至每晚房價的固定折扣 (或指定 applied_nights 時的最低 N 晚房價)。AmountAfterTax如未指定 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、percentage_of_base、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，則

    promotion rate = 300
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night 0..1 float

必須提供 percentage、percentage_of_base、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，則每晚的價格會減半。
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 指定。必須設為 base 或 none。系統會合併每晚最優惠的「每日最佳」折扣，並視為單一住宿折扣 (即 Discount)，同時遵守設定的堆疊類型。系統會比較這個合併折扣與其他符合資格的 <折扣>促銷活動，並可與其他折扣一併使用，找出最划算的折扣或組合。系統會選取 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每晚房價) 扣除的固定金額。系統會假設幣別與每晚房價相同。如果這個值大於每晚房價的總和，則結果為零。

範例：

  • 如果單晚的 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：系統會選取並套用最符合資格的 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"}。

如要設定 StayDates 範圍，在每週特定日子提供促銷活動，請將 start 日期設為目前日期，且不要設定 end，以免促銷活動到期。
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start 0..1 Date or YearlessDate 日期範圍的開始日期 (以資源時區為準)。這個日期必須早於或等於「end」日期。如果未指定 start，日期範圍的開始日期實際上不受限制。

如果未提供 end 值，則應指定 start 值。
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end 0..1 Date or YearlessDate 日期範圍的結束日期 (以資源時區為準，含此日期)。這個日期必須與 start 日期相同或晚於該日期。如果未指定 end，則日期範圍會從 start 日起無限期有效。

如果未提供 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 UserCountries 規格的類型。

有效值為 include 和 exclude。

如果 UserCountries type 設為 include，促銷活動會套用至所列國家/地區的使用者。

如果 UserCountries type 為 exclude， 促銷活動會套用至所列國家/地區以外的使用者。

如果未設定 UserCountries 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 區域代碼。

範例

每個房源最多只能有 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 種不同的堆疊類型

以下範例顯示會套用三種不同促銷活動 (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 日 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 折扣

以下範例會針對指定預訂日期範圍，每四晚住宿提供兩晚 5 折優惠。如果行程為十晚，則總共有四晚可享 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>

下例會針對指定入住日期範圍，每入住三晚就提供一晚 5 折優惠。只有重疊的住宿夜數才符合折扣資格。以下行程的入住日期為 2022 年 1 月 1 日，退房日期為 2022 年 1 月 7 日，符合資格的住宿晚數和折扣適用情形如下。

  • 2022-01-01 (住宿)
  • 2022-01-02 (住宿)
  • 2022-01-03
  • 2022-01-04 (折扣價)
  • 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 折。評估期間，系統只會套用 85 折優惠，因為折扣值較低。

<?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。

因此，在住宿期間，「fiesta」促銷活動每晚折扣 $5 美元，總共折扣 $10 美元。由於「fiesta」的堆疊類型設為 any，因此可以與最佳每日折扣組合堆疊。如果設為 base，系統只會套用每日最佳折扣組合或「fiesta」折扣。詳情請參閱 Stacking 的說明。

`Overall, the price of the stay receives a 20 + 50 + 10 = 80 fixed amount discount.

回應

語法

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>