促銷內容

總覽

您可以使用這個 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 相符。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> 的促銷活動，可以將 <Discount> 設為 0 的 percentage。

如果已設定堆疊，則單一住宿可套用多個含有 <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 屬性。

amount_per_night 會套用於稅金和費用，前提是這些項目已納入使用 AmountAfterTax 表示的每晚房價，但不適用於使用 TaxFeeInfo 指定的項目。
Promotions / HotelPromotions / Promotion / Floor 0..1 Floor

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

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

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

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

範例：

計算 1 晚住宿的價格，其中 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 屬性。

amount_per_night 會套用在使用 AmountAfterTax 的房價中包含的稅金和費用，但不會套用使用 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 每晚房價總和) 中扣除的固定金額。並假設使用與每晚房價相同的幣別。如果這個值大於每晚房價的總和，則產生的值為零。

範例：

  • 如果我們要為 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、percentage_of_base、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、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，

    促銷率 = 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，則每晚的折扣金額為 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 之間 (含 1 和 99)。如果有多項促銷活動具有相同的排名，系統會隨機選取並套用其中一個。
Promotions / HotelPromotions / Promotion / BestDailyDiscount 1 Discount

必須指定 Discount 或 BestDailyDiscount 其中一個。

指定可套用於住宿一晚的每日折扣。這與 Discount 相反，後者會將折扣套用至整個住宿體驗。

每個資源都可能有一個被視為「每日最佳」的促銷活動群組。也就是說，系統會為每晚的住宿，選取並套用符合資格且可為該晚提供最優惠折扣的「每日最佳」促銷活動。

Stacking 可使用 BestDailyDiscount 指定。必須設為 base 或 none。系統會將每晚最優惠的「每日」折扣合併，並視為單一住宿折扣 (即 Discount)，同時遵循設定的堆疊類型。系統會比較這項折扣與其他符合資格的 <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 每晚房價 (或 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。這個值會對應至 Transaction (Property Data) 訊息中 <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> 值參照。(其 <RoomID> 值也會由 OTA_HotelRateAmountNotifRQ 訊息中的 InvTypeCode 屬性參照)。
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"}。

如果您想設定 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>


重疊所有促銷活動3 種不同的堆疊類型無堆疊類型

以下範例說明如何為擁有一或多項新促銷活動的資源疊加 <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>

以下範例說明會套用三種不同促銷活動的情況 (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>


預訂期時長範圍預訂日期 DateTime 邊界無年份的日期範圍

以下範例說明使用 BookingWindow 元素的情況，其中開始和結束邊界定義為 ISO 8601 時間長度類型。根據預訂時間限制，你必須在抵達前一天的 18:00 前或之後，以及抵達前 2 天的 12:00 前或之後預訂。

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <BookingWindow min="P1DT6H" max="P2DT12H"/>
      <Discount percentage="20"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

以下範例顯示 BookingDates 元素與 start 和 end 屬性一起用於 DateTime 類型的情況。根據這項預訂日期限制，預訂時間必須介於 2020-07-01 06:30 至 2020-07-02 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>


免費住宿晚數折扣排名選取BestDailyDiscount

以下範例顯示，在指定的預訂日期範圍內，每住四晚可享兩晚 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>

下例會針對指定入住日期範圍，為每住滿 3 晚的訂房提供 50% 的折扣。只有重疊的住宿晚數才能符合折扣資格。下列行程的入住日期為 2022-01-01，退房日期為 2022-01-07，適用的住宿晚數和折扣如下所示。

  • 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>


以下範例提供兩種折扣，一個是 20%，另一個是 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，為兩晚住宿提供折扣。

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

就第二晚而言，「may」促銷活動提供的折扣比「general」折扣還要優惠。因此，當您選取「may」時，固定折扣金額為 50。

接著，針對住宿，以「fiesta」促銷活動的折扣為每晚 5 美元，或總計 10 美元。由於「fiesta」的堆疊類型設為 any，因此可與最佳每日折扣組合堆疊。如果設為 base，系統只會套用最佳每日折扣或「fiesta」折扣的組合。詳情請參閱 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>