促銷內容

如果您有為多個帳戶提供動態饋給的後端，這個值必須與同一個帳戶的 <OTA_HotelRateAmountNotifRQ> 和 <OTA_HotelAvailNotifRQ> 訊息 <RequestorID> 元素中指定的 ID 屬性值相符。

房源的促銷活動。每項促銷活動都只適用於單一房源。

除非使用 <Stacking>，否則在多項促銷活動符合資格時，系統會將折扣幅度最大的促銷活動套用至預訂。

如果指定，則值必須為 "overlay"。如果值為 "overlay"，系統會先刪除所有已儲存的促銷活動，再儲存目前訊息中指定的促銷活動。

如未指定，則目前訊息中指定的每項促銷活動會是下列任一情況：

• Added (如果儲存的宣傳活動都沒有相同的 id)
• Updated (如果儲存的促銷活動具有相同的 id)
• Deleted (如果儲存的促銷活動具有相同的 id，且目前訊息中指定的促銷活動 action 屬性值為 "delete")

住宿的單一促銷活動。請注意，如果未指定 action="overlay" 和 <Promotion>，系統會刪除資源的所有促銷活動。

如需使用超過 99 項促銷活動，請與客戶技術顧問 (TAM) 聯絡。

如有指定，值必須為 delete。如果未指定，且系統未儲存相同 id 的促銷活動，則會儲存這項促銷活動。否則，如果未指定，且儲存的促銷活動具有相同的 id，則會更新現有的促銷活動。

如果指定 delete，系統會刪除儲存的促銷活動，該促銷活動具有相同的 id。使用 delete 時，請勿在 <Promotion> 中加入任何子元素。此外，delete 也不得與 <HotelPromotions action="overlay"/> 搭配使用。

範圍的開始日期或時間 (以資源所在時區為準)，包含在內。

• start 指定的日期或時間範圍必須早於 (或等於) end 指定的日期或時間範圍。
• 如果未指定 start，則範圍的開始時間實際上是無限制的。
• 如果 start 填入的日期為「YYYY-MM-DD」，系統會將其解讀為時間日期「YYYY-MM-DDT00:00:00」。

範圍的結束日期或時間 (以資源的時區為準)，包含在範圍內。

• end 指定的日期或日期時間必須晚於 (或等於) start 指定的日期或日期時間。
• 如果未指定 end，則範圍的結束時間實際上是無限制的。
• 如果 end 提供的日期為「YYYY-MM-DD」，系統會將其解讀為時間「YYYY-MM-DDT23:59:59」。

在日期範圍內允許的星期幾。如果未指定，系統會允許在指定日期範圍內的所有日子。字串中的每個字元都會指定一天。舉例來說，「MTWHF」會指定日期範圍內允許的星期幾。

有效的字元包括：

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

任何字元組合皆可使用。

有效的值類型包括：

• 整數：入住日期前的天數。舉例來說，如果值為 30，表示促銷活動只適用於入住日期前至少 30 天的預訂。
• ISO 8601 時間長度 (天、小時和分鐘)：入住日期前的天數 (以及選填的時間長度)。舉例來說，如果值為 P30D，表示促銷活動只適用於入住日期前至少 30 天的預訂。如果值為 P30DT6H，則必須在抵達日期前 30 天的 18:00 或之前預訂。

有效的值類型包括：

• 整數：入住日期前的天數。舉例來說，如果值為 30，表示促銷活動只適用於入住日期前 30 天內的預訂。
• ISO 8601 時間長度 (天、小時和分鐘)：入住日期前的天數 (以及選填的時間長度)。舉例來說，如果值為 P30D，表示促銷活動只適用於入住日期前 30 天內的預訂。值為 P30DT6H 時，必須在抵達前 30 天的 18:00 或之後預訂。

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

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

如果已設定堆疊，則單一住宿可套用多個含有 <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 是更嚴格的整體上限，但這與實際情況無關，因為它只適用於該促銷活動，且整個促銷活動堆疊中並沒有單一上限。

套用折扣後，每晚房價可設定的最高金額。

如果也指定了 <Floor> 元素，則此值必須設為大於或等於 <Floor> 中的 amount_per_night 屬性。

amount_per_night 會套用在使用 AmountAfterTax 的房價中包含的稅金和費用，但不會套用使用 TaxFeeInfo 指定的稅金和費用。

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

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

即使免費住宿已套用 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 是更嚴格的整體下限，但這與實際情況無關，因為它只適用於該促銷活動，且整個促銷活動堆疊中不可能有單一下限。

套用折扣後，可設定的每晚房價最低金額。

如果也指定了 <Ceiling> 元素，則此值必須設為小於或等於 <Ceiling> 中的 amount_per_night 屬性。

amount_per_night 會套用在使用 AmountAfterTax 的房價中包含的稅金和費用，但不會套用使用 TaxFeeInfo 指定的稅金和費用。

指定必須在何時入住才能適用促銷活動的日期範圍。如果您要刪除一或多項促銷活動，則不需要使用這個元素。

系統也支援 YearlessDate 格式。

• 如果 start 或 end 其中一個是無年份日期，則兩者都必須填入無年份日期。
• 無年份日期範圍不得跨越新年。請改為以兩個相鄰的日期範圍表示範圍。例如，{"12-29", "01-05"} 可以表示為 {"12-29", "12-31"} 和 {"01-01", "01-05"}。

在日期範圍內允許的星期幾。如果未指定，系統會允許在指定日期範圍內的所有日子。字串中的每個字元都會指定一天。舉例來說，「MTWHF」會指定日期範圍內允許的星期幾。

有效的字元包括：

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

任何字元組合皆可使用。

指定促銷活動適用的退房日期範圍。如果您要刪除一或多項促銷活動，則不需要使用這個元素。

系統也支援 YearlessDate 格式。

• 如果 start 或 end 其中一個是無年份日期，則兩者都必須填入無年份日期。
• 無年份日期範圍不得跨越新年。請改為以兩個相鄰的日期範圍表示範圍。例如，{"12-29", "01-05"} 可以表示為 {"12-29", "12-31"} 和 {"01-01", "01-05"}。

在日期範圍內允許的星期幾。如果未指定，系統會允許在指定日期範圍內的所有日子。字串中的每個字元都會指定一天。舉例來說，「MTWHF」會指定日期範圍內允許的星期幾。

有效的字元包括：

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

任何字元組合皆可使用。

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

指定要套用於這項促銷活動的折扣。

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

必須提供 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%。

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

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

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

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

這個屬性應只與 percentage 或 fixed_amount_per_night 搭配使用。

套用折扣的住宿晚數，從最便宜的開始。必須是介於 1 到 99 的整數。如未指定，系統會套用折扣到所有晚數。

適用折扣的必要住宿晚數。每項折扣都會套用至不同的住宿晚數區間。

舉例來說，如果住宿天數為 10 晚，stay_nights 為 4 (且 repeats 為 true)，則有兩個住宿天數區段：第 1 到 4 晚和第 5 到 8 晚；第 9 和 10 晚不屬於住宿天數區段。

折扣是否可套用至多個住宿晚數區間。如果為 false，則只有行程一開始的住宿夜數會提供折扣。如果為 true，則所有住宿天數區間都會提供折扣。

舉例來說，如果 stay_nights 為 4，而行程為 10 晚，如果 repeats 為 true，則 2 個區段會打折 (第 1 到第 4 晚和第 5 到第 8 晚)；但如果 repeats 為 false，則只有 1 個區段會打折 (第 1 到第 4 晚)。

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

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

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

Stacking 可使用 BestDailyDiscount 指定。必須設為 base 或 none。系統會將每晚最優惠的「每日」折扣合併，並視為單一住宿折扣 (即 Discount)，同時遵循設定的堆疊類型。系統會比較這項合併折扣，並可與其他符合資格的 <Discount> 促銷活動合併使用，以便找出提供最優折扣的折扣或組合。系統會選取 BestDailyDiscount 組合或單一 Discount (以較低價格為準)，並套用至 base 堆疊類型。

StayDates 可搭配這類折扣指定，但 application 必須設為 overlap

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

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

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

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

除非同時指定 <Discount>，否則「不應」指定此元素。

與會員方案相關聯的 費率規範 ID。

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

• any：可與任何其他促銷活動合併使用 (none 除外)，但無法保證促銷活動的套用順序。
• base：系統會先選取並套用最符合資格的 base 促銷活動，然後再套用其他促銷活動。這項功能先前稱為 base_only。
• second：系統會在 base 促銷活動 (如適用) 結束後，在 any 促銷活動開始前，選取並套用最適合的 second 促銷活動。
• none：不得與其他促銷活動併用。

在允許的組合中，系統會將可產生最大折扣的促銷活動套用至費率。

說明促銷活動的套用方式。

有效值如下：

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

必須一律指定這個屬性。

• 如果 <Discount> 指定 percentage，且 application 設為 all 或 any，則折扣會以整個住宿期的百分比套用。
• 如果 <Discount> 指定 percentage，且 application 設為 overlap，系統會以重疊住宿晚數的每晚房價百分比套用折扣。
• <Discount> 指定 fixed_amount 和 application 設為 overlap 是無效的組合。
• <FreeNights> 支援所有 application 值。請注意，對於 overlap，只有重疊的住宿晚數才會納入折扣條件考量。

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

系統也支援 YearlessDate 格式。

• 如果 start 或 end 其中一個是無年份日期，則兩者都必須填入無年份日期。
• 無年份日期範圍不得跨越新年。請改為以兩個相鄰的日期範圍表示範圍。例如，{"12-29", "01-05"} 可以表示為 {"12-29", "12-31"} 和 {"01-01", "01-05"}。

如果您想設定 StayDates 範圍，讓促銷活動在星期中的特定幾天生效，請將 start 日期設為目前日期，並移除 end，以免促銷活動過期。

如果未提供 end 值，請指定 start 值。

如果未提供 start 值，請指定 end 值。

在日期範圍內允許的星期幾。如果未指定，系統會允許在指定日期範圍內的所有日子。字串中的每個字元都會指定一天。舉例來說，「MTWHF」會指定日期範圍內允許的星期幾。

有效的字元包括：

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

任何字元組合皆可使用。

有效值為 include 和 exclude。

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

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

如果未設定 UserCountries type，系統會將其視為 include，並將促銷活動套用至列出國家/地區的使用者。

每則訊息都會提供 <Success> 或 <Issues>。

每則訊息都會提供 <Success> 或 <Issues>。

遇到的問題類型。

有效值為 warning、error 和 failure。