プロモーション

概要

この API を使用すると、可能な割引を指定できます。指定されたプロモーションの中で、最も低い価格になる対象プロモーションまたはプロモーション セットが適用されます。条件が満たされたときに料金を増減できる任意の料金調整をサポートする API をお探しの場合は、Rate Modifications API をご検討ください。両方の API が存在する場合、料金の変更はプロモーションの前に適用されます。

リクエスト

構文

Promotions メッセージでは、次の構文を使用します。

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner= "partner_key"
            id="message_ID"
            timestamp="timestamp">
  <HotelPromotions hotel_id="HotelID" action="[overlay]">
    <Promotion id="PromotionID" action="[delete]">
      <BookingDates>
        <DateRange start="YYYY-MM-DD[THH:mm:ss]" end="YYYY-MM-DD[THH:mm:ss]"
          days_of_week="MTWHFSU_or_subset"/>
        <DateRange start="YYYY-MM-DD[THH:mm:ss]" end="YYYY-MM-DD[THH:mm:ss]"
          days_of_week="MTWHFSU_or_subset"/>
      </BookingDates>
      <BookingWindow min="integer_or_duration" max="integer_or_duration"/>
      <Ceiling amount_per_night="float"/>
      <Floor amount_per_night="float"/>
      <CheckinDates>
        <DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </CheckinDates>
      <CheckoutDates>
        <DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </CheckoutDates>
      <!-- Specify only one of percentage, 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>

要素と属性

Promotions メッセージには、次の要素と属性があります。

要素 / @属性 発生回数 タイプ 説明
Promotions 1 Complex element Promotions メッセージのルート要素。
Promotions / @partner 1 string このメッセージのパートナー アカウント。この文字列の値は、Hotel Center の [アカウント設定] ページに表示されている [パートナーキー] の値です。

複数のアカウントのフィードを提供するバックエンドを使用している場合、この値は、同じアカウントの <OTA_HotelRateAmountNotifRQ> メッセージと <OTA_HotelAvailNotifRQ> メッセージの <RequestorID> 要素で指定されている ID 属性値に一致する必要があります。
Promotions / @id 1 string このリクエスト メッセージの一意の識別子。この値はレスポンス メッセージ内で返されます。使用できる文字は、a ～ z、A ～ Z、0 ～ 9、_（アンダースコア）、-（ダッシュ）です。
Promotions / @timestamp 1 DateTime このメッセージの作成日時。
Promotions / HotelPromotions 0..n HotelPromotions

宿泊施設のプロモーション。各プロモーションは 1 つの宿泊施設に適用されます。

<Stacking> を使用する場合を除き、複数のプロモーションが対象となる場合、割引が最大であるプロモーションが予約に適用されます。
Promotions / HotelPromotions / @hotel_id 1 string 宿泊施設の一意の識別子。この値は、ホテルリスト フィードの <listing> 要素の <id> を使用して指定した HotelID と一致する必要があります。HotelID は Hotel Center にも表示されます。
Promotions / HotelPromotions / @action 0..1 enum

指定する場合、値は "overlay" である必要があります。値が "overlay" の場合、現在のメッセージで指定されたプロモーションを保存する前に、保存されているすべてのプロモーションが削除されます。

指定しない場合、現在のメッセージで指定されている各プロモーションは次のいずれかになります。

  • Added（保存済みプロモーションに同じ id が含まれない場合）
  • Updated（保存済みプロモーションに同じ id がある場合）
  • Deleted（保存済みプロモーションに同じ id があり、現在のメッセージで指定されているプロモーションの action 属性の値が "delete" である場合）
Promotions / HotelPromotions / Promotion 0..99 Promotion

宿泊施設の 1 件のプロモーション。action="overlay" と <Promotion> が指定されていない場合、宿泊施設のプロモーションはすべて削除されます。

99 件以上のプロモーションを使用する必要がある場合は、テクニカル アカウント マネージャー（TAM）にお問い合わせください。
Promotions / HotelPromotions / Promotion / @id 1 string プロモーションの一意の識別子。最大 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 プロモーションを適用するために予約が行われる必要があるタイミングを定義する 1 つ以上の期間のコンテナ。
Promotions / HotelPromotions / Promotion / BookingDates / DateRange 1..99 DateRange プロモーションを適用するために予約が行われる必要がある期間。
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start 0..1 Date または DateTime

期間の開始日または日時（宿泊施設のタイムゾーンに基づく）。

  • start で指定された日付または日時が、end で指定された日付または日時より前（または同じ）である必要があります。
  • start を指定しない場合、開始時間に関する限り、期間は実質的に無制限となります。
  • start に日付「YYYY-MM-DD」が入力されている場合、日時「YYYY-MM-DDT00:00:00」として解釈されます。
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end 0..1 Date または DateTime

期間の終了日または日時（宿泊施設のタイムゾーンに基づく）。

  • end で指定された日付または日時は、start で指定された日付または日時以降の日付（または同じ日付）にする必要があります。
  • end を指定しない場合、終了時刻に関する限り、期間は実質的に無制限となります。
  • end が日付「YYYY-MM-DD」として指定されている場合、日時「YYYY-MM-DDT23:59:59」として解釈されます。
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week 0..1 string

期間で許可される曜日です。指定しないと、期間内のすべての曜日が許可されます。文字列の各文字で曜日を指定します。たとえば、「MTWHF」は、期間で平日を許可することを指定します。

有効な文字は次のとおりです。

  • M（月曜日）
  • T（火曜日）
  • W（水曜日）
  • H（木曜日）
  • F（金曜日）
  • S（土曜日）
  • U（日曜日）

任意の文字の組み合わせが有効です。
Promotions / HotelPromotions / Promotion / BookingWindow 0..1 BookingWindow チェックイン日を基準にして予約が行われる必要がある期間を指定します（宿泊施設のタイムゾーンに基づく）。たとえば、予約期間には、チェックインの 7 日前から 180 日前までを設定できます。
Promotions / HotelPromotions / Promotion / BookingWindow / @min 0..1 integer or duration プロモーションを適用するために予約が行われる必要がある場合の、チェックイン前の最小期間。これが指定されていない場合、または値が 0 の場合、最小値はありません。

有効な値の型は次のとおりです。

  • Integer: チェックイン日までの日数。たとえば、値 30 は、プロモーションがチェックイン日の 30 日前以上の予約にのみ適用されることを示します。
  • ISO 8601 の期間（日数、時間、分）: チェックイン日までの日数（オプションで時間/分）。たとえば、値 P30D は、プロモーションがチェックイン日の 30 日前以上の予約にのみ適用されることを示します。値 P30DT6H は、到着日の 30 日前の 18:00 までに予約する必要があることを示します。
Promotions / HotelPromotions / Promotion / BookingWindow / @max 0..1 integer or duration プロモーションを適用するために予約が行われる必要がある場合の、チェックイン前の最大日数です。これが指定されていない場合、または値が 0 の場合、最大値はありません。

有効な値の型は次のとおりです。

  • Integer: チェックイン日までの日数。たとえば、値 30 は、プロモーションがチェックイン日の 30 日前までの予約にのみ適用されることを示します。
  • ISO 8601 の期間（日数、時間、分）: チェックイン日までの日数（オプションで時間/分）。たとえば、値 P30D は、プロモーションがチェックイン日の 30 日前までの予約にのみ適用されることを示します。値 P30DT6H は、到着日の 30 日前の 18:00 以降に予約する必要があることを示します。
Promotions / HotelPromotions / Promotion / Ceiling 0..1 Ceiling

プロモーションを適用した後に料金に設定できる最大値に関する制限を定義します。

プロモーションでは常に <Discount> または <BestDailyDiscount> を指定する必要があります。そのため、<Ceiling> のみを適用するプロモーションを作成するには、percentage を 0 にして <Discount> を設定します。

重ね合わせが構成されている場合、<Ceiling> を含む複数のプロモーションが 1 回の滞在に適用されることがあります。各プロモーションの割引が適用され、その直後に上限が適用されます。次の例は、各上限がスタック内の次の昇進計算にどのように影響するかを示しています。

例:

AmountBeforeTax が 100 で、2 つのプロモーションがスタックされている 1 泊の料金:

  1. 重ねがけタイプが base、fixed_amount が 25、上限が amount_per_night 60 のプロモーション
  2. 重ねがけタイプが second、fixed_amount が 25、上限が amount_per_night 90 のプロモーション

計算順序は次のとおりです。

  1. base プロモーションが最初に適用され、AmountBeforeTax が 75 に割引されますが、上限により 60 に引き下げられます。
  2. second プロモーションで AmountBeforeTax が 60 から 35 に割引されます。これは上限 90 を下回っているため、2 つ目の上限は適用されません。最終的なレートは 35 です。

60 が全体的な上限としてより厳しいという点は、その上限が独自のプロモーションにのみ有効であり、プロモーション スタック全体にまたがる単一の上限が存在しないため、無関係です。
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night 1 float

割引を適用した後の宿泊料金の最大額。

<Floor> 要素も指定する場合は、<Floor> の amount_per_night 属性以上の値に設定する必要があります。

amount_per_night は、AmountAfterTax を使用して 1 泊あたりの料金に含まれる税金と手数料に適用されますが、TaxFeeInfo を使用して指定された税金と手数料には適用されません。
Promotions / HotelPromotions / Promotion / Floor 0..1 Floor

プロモーションを適用した後に料金に設定できる最小値に関する制限を定義します。

プロモーションでは常に <Discount> または <BestDailyDiscount> を指定する必要があります。そのため、<Floor> のみを適用するプロモーションを作成するには、percentage を 0 にして <Discount> を設定します。

無料宿泊に 100% 割引が適用されている場合でも、<FreeNights> 割引には <Floor> ロジックが適用されます。

重ね合わせが構成されている場合、<Floor> を含む複数のプロモーションが 1 回の滞在に適用されることがあります。各プロモーションの割引が適用され、その後すぐに最小価格が適用されます。次の例は、各階層がスタック内の次のプロモーション計算にどのように影響するかを示しています。

例:

AmountBeforeTax が 100 で、2 つのプロモーションがスタックされている 1 泊の料金:

  1. スタッキング タイプが base、fixed_amount が 25、amount_per_night が 90 のプロモーション
  2. スタッキング タイプが second、fixed_amount が 25、下限が amount_per_night 60 のプロモーション

計算順序は次のとおりです。

  1. base プロモーションが最初に適用され、AmountBeforeTax が 75 に割引されますが、その後、下限によって 90 に引き上げられます。
  2. second プロモーションで AmountBeforeTax が 90 から 65 に割引されます。これは 60 の下限を超えているため、2 つ目の下限は適用されません。最終的なレートは 65 です。

90 が全体的な下限としてより厳しいという点は、そのプロモーションにのみ有効であり、プロモーション スタック全体にわたる単一の下限を設定できないため、無関係です。
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night 1 float

割引が適用された後の宿泊料金の最小額。

<Ceiling> 要素も指定する場合は、<Ceiling> の amount_per_night 属性以下の値に設定する必要があります。

amount_per_night は、AmountAfterTax を使用して 1 泊あたりの料金に含まれる税金と手数料に適用されますが、TaxFeeInfo を使用して指定された税金と手数料には適用されません。
Promotions / HotelPromotions / Promotion / CheckinDates 0..1 CheckinDates プロモーションを適用するためにチェックインが行われる必要があるタイミングを定義する 1 つ以上の期間のコンテナ。
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange 1..20 DateRange

プロモーションを適用するためにチェックインが行われる必要があるタイミングを指定する期間。1 件以上のプロモーションを削除する場合、この要素は不要です。

YearlessDate 形式もサポートされています。

  • start または end のいずれかが年指定なしの日付になっている場合、どちらの日付も年指定なしの日付として入力する必要があります。
  • 年指定なしの期間は、新年をまたいで指定することはできません。代わりに、期間を 2 つの隣接する期間として表します。たとえば、{"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 プロモーションを適用するためにチェックアウトが行われる必要があるタイミングを定義する 1 つ以上の期間のコンテナ。
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange 1..20 DateRange

プロモーションを適用するためにチェックアウトが行われる必要があるタイミングを指定する期間。1 件以上のプロモーションを削除する場合、この要素は不要です。

YearlessDate 形式もサポートされています。

  • start または end のいずれかが年指定なしの日付になっている場合、どちらの日付も年指定なしの日付として入力する必要があります。
  • 年指定なしの期間は、新年をまたいで指定することはできません。代わりに、期間を 2 つの隣接する期間として表します。たとえば、{"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 プロモーションの対象となるユーザー デバイスのタイプを 1 つ定義します。
Promotions / HotelPromotions / Promotion / Devices / Device / @type 1 enum デバイスのタイプ。値は desktop、tablet、または mobile にする必要があります。
Promotions / HotelPromotions / Promotion / Discount 1 Discount

Discount または BestDailyDiscount のいずれか 1 つを指定する必要があります。

このプロモーションに適用する割引を指定します。
Promotions / HotelPromotions / Promotion / Discount / @percentage 0..1 float

percentage、percentage_of_base、fixed_amount、fixed_amount_per_night、fixed_price、fixed_price_per_night のいずれか 1 つを指定する必要があります。

割引率を指定する 0 ～ 100 の 10 進値。これは AmountAfterTax に適用されます（AmountAfterTax が指定されていない場合は AmountBeforeTax に適用されます）。

例:

  • AmountAfterTax が 100 で、percentage が 20 の場合:

    プロモーション料金 = AmountAfterTax x (1 - 割引率)

    80.00 = 100 x (1 - 0.2)

  • AmountBeforeTax が 100 で、percentage が 20 で、TaxFeeInfo が税金 10 を指定する場合:

    プロモーション料金 = AmountBeforeTax x (1 - 割引率) + 税金

    90.00 = 100 x (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 のいずれか 1 つを指定する必要があります。

基本割引の割合を指定する 0 ～ 100 の 10 進値。percentage と同様に、AmountAfterTax に適用されます（AmountAfterTax が指定されていない場合は AmountBeforeTax に適用されます）。

percentage とは異なり、この割引は、以前に適用されたプロモーションに関係なく、常に基本料金の割合として計算されます。

例:

  • 100 円の 1 泊の宿泊に 2 つのプロモーションが順番に適用されるとします。1 つ目は通常の 10% の割引率で、2 つ目は基本割引の 10% の割引率です。両方のプロモーションで 10% の割引が適用されるため、割引後の料金は 80 になります。2 つ目のプロモーションが通常の割引率の場合、2 つ目のプロモーションで 90% の 10% が割引されるため、割引後の料金は 81 になります。
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 のいずれか 1 つを指定する必要があります。

AmountAfterTax の宿泊料金の合計（または AmountAfterTax が指定されていない場合は AmountBeforeTax の宿泊料金の合計）から差し引かれる定額。宿泊料金と同じ通貨であるとみなされます。これが宿泊料金の合計より大きい場合、結果の値は 0 になります。

例:

  • 1 泊の料金を計算する際に、AmountBeforeTax が 90、AmountAfterTax が 100、fixed_amount が 20 の場合:

    プロモーション料金 = AmountAfterTax - 固定割引

    80.00 = 100 - 20

  • 1 泊の料金を計算する際に、AmountBeforeTax が 100、fixed_amount が 20、TaxFeeInfo で税率 8% を指定する場合:

    プロモーション料金 = (AmountBeforeTax - 固定割引) x (1 + 税率)

    86.40 = (100 - 20) x 1.08

  • 1 泊の料金を計算する際に、AmountBeforeTax が 50、fixed_amount が 60、TaxFeeInfo で税金 10 を指定する場合:

    プロモーション料金 = (AmountBeforeTax - 固定割引) x 税金

    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 のいずれか 1 つを指定する必要があります。

AmountAfterTax の各宿泊料金（applied_nights が指定されている場合は最も最安の N）に適用される固定割引。AmountAfterTax が指定されていない場合は、AmountBeforeTax に適用されます。宿泊料金と同じ通貨であるとみなされます。fixed_amount_per_night が 1 泊の料金を上回る場合、その 1 泊の料金は 0 に引き下げられます。割引により、1 泊の料金が負の値になることはありません。

例:

  • 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 のいずれか 1 つを指定する必要があります。

1 泊の料金として AmountAfterTax が指定されている場合、税金と手数料を含む宿泊料金が指定された値に設定されます。AmountBeforeTax が指定されている場合、AmountAfterTax が指定されているかどうかにかかわらず、滞在の税抜き料金が指定された値に設定されます。宿泊料金と同じ通貨であるとみなされます。

AmountAfterTax が税率を反映するものである場合、AmountBeforeTax に固定価格を設定すると、税金と手数料が不正確になる可能性があります。通常は、TaxFeeInfo を使用して宿泊施設の税金と手数料を指定することを強くおすすめします。

例:

  • 1 泊の料金を計算する際に、AmountBeforeTax が 90、AmountAfterTax が 100、fixed_price が 80 の場合、プロモーション料金は 80 です。
  • 1 泊の料金を計算する際に、AmountBeforeTax が 100、fixed_amount が 80、TaxFeeInfo で税率 8% を指定する場合:

    プロモーション料金 = 固定価格 x (1 + 税率)

    86.40 = 80 x 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 のいずれか 1 つを指定する必要があります。

AmountAfterTax 1 泊あたりの料金が指定されている場合、宿泊の各泊の料金（税金と手数料を含む）が指定された値に設定されます。AmountBeforeTax が指定されている場合、AmountAfterTax が指定されているかどうかにかかわらず、宿泊 1 泊あたりの税抜き料金が指定された値に設定されます。宿泊料金と同じ通貨であるとみなされます。

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 泊目の 2 つの宿泊日セグメントがあります。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 つが任意に選択されて適用されます。
Promotions / HotelPromotions / Promotion / BestDailyDiscount 1 Discount

Discount または BestDailyDiscount のいずれか 1 つを指定する必要があります。

1 泊に適用できる 1 日あたりの割引を指定します。これは、滞在全体に割引を適用する Discount とは対照的です。

各プロパティには、「1 日あたりのベスト」と見なされるプロモーションのグループを 1 つ設定できます。つまり、宿泊する 1 泊ごとに、その夜に適用できる割引率が最も高い「1 日あたりの最適な」プロモーション 1 つが選択され、適用される可能性があります。

Stacking は BestDailyDiscount で指定できます。base または none に設定する必要があります。1 泊あたりの割引率が最も高い「1 泊あたりの最適な」割引が組み合わせられ、構成されたスタッキング タイプに従って 1 回の宿泊の割引（Discount）として扱われます。この組み合わせ割引は、他の対象となる <Discount> プロモーションと比較され、組み合わせて適用できます。これにより、最も割引率の高いプロモーションまたは組み合わせが見つかります。base のスタッキング タイプには、BestDailyDiscount の組み合わせまたは単一の Discount のいずれか（低い方の価格）が選択され、適用されます。

このタイプの割引で StayDates を指定できますが、application は overlap に設定する必要があります。

.
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage 0..1 float

percentage、fixed_amount、fixed_price のいずれか 1 つのみが必要です。

割引率を指定する 0 ～ 100 の 10 進値。これは AmountAfterTax に適用されます（AmountAfterTax が指定されていない場合は AmountBeforeTax に適用されます）。

例:

  • 1 泊の AmountAfterTax が 100、percentage が 20 の場合:

    プロモーション料金 = AmountAfterTax x (1 - 割引率)

    80.00 = 100 x (1 - 0.2)

  • 1 泊の AmountBeforeTax が 100、percentage が 20、TaxFeeInfo が税金 10 を指定する場合:

    プロモーション料金 = AmountBeforeTax x (1 - 割引率) + 税金

    90.00 = 100 x (1 - 0.2) + 10
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount 0..1 float

percentage、fixed_amount、fixed_price のいずれか 1 つのみが必要です。

1 泊あたりの AmountAfterTax の宿泊料金（または AmountAfterTax が指定されていない場合は AmountBeforeTax の宿泊料金）から差し引かれる定額。宿泊料金と同じ通貨であるとみなされます。これが宿泊料金の合計より大きい場合、結果の値は 0 になります。

例:

  • 1 泊の AmountBeforeTax が 90、AmountAfterTax が 100、fixed_amount が 20 の場合:

    プロモーション料金 = AmountAfterTax - 固定割引

    80.00 = 100 - 20

  • 1 泊の AmountBeforeTax が 100、fixed_amount が 20、TaxFeeInfo で税率 8% を指定する場合:

    プロモーション料金 = (AmountBeforeTax - 固定割引) x (1 + 税率)

    86.40 = (100 - 20) x 1.08
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price 0..1 float

percentage、fixed_amount、fixed_price のいずれか 1 つのみが必要です。

AmountAfterTax 1 泊の料金が指定されている場合、宿泊 1 泊の料金（税金と手数料を含む）が指定された値に設定されます。AmountBeforeTax が指定されている場合、AmountAfterTax が指定されているかどうかにかかわらず、滞在の税抜き料金が指定された値に設定されます。宿泊料金と同じ通貨であるとみなされます。

例:

  • 1 泊の AmountBeforeTax が 90、AmountAfterTax が 100、fixed_price が 80 の場合、プロモーション料金は 80 です。
  • 1 泊の AmountBeforeTax が 100、fixed_amount が 80、TaxFeeInfo で税率 8% を指定する場合:

    プロモーション料金 = 固定価格 x (1 + 税率)

    86.40 = 80 x 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 1 日の客室料金（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 料金プランを指定します。料金プランは、パッケージ、料金、空室状況の組み合わせで定義されます。また、Transaction（宿泊施設データ）、OTA_HotelRateAmountNotifRQ、OTA_HotelAvailNotifRQ の各メッセージにより定義され、PackageID により識別されます。
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id 1 string 料金プランの一意の識別子。この値は PackageID の値に対応します。PackageID の値は、Transaction（宿泊施設データ）メッセージの <PackageData> と、<OTA_HotelRateAmountNotifRQ> メッセージと <OTA_HotelAvailNotifRQ> メッセージ両方の <StatusApplicationControl> の RatePlanCode 属性にあります。最大 50 文字まで使用できます。
Promotions / HotelPromotions / Promotion / RoomTypes 0..1 RoomTypes プロモーションを適用する客室タイプのリストのコンテナ。プロモーションは、指定された各 <RoomType> に適用されます。<RoomTypes> を指定しない場合、すべての客室にプロモーションが適用されます。
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType 1..n RoomType 客室タイプを指定します。客室タイプは、Transaction（宿泊施設データ）メッセージの <RoomData> 要素で定義され、<RoomID> 値を使用して参照されます（その <RoomID> 値は、OTA_HotelRateAmountNotifRQ メッセージの InvTypeCode 属性でも参照されます）。
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id 1 string 在庫の一意の識別子（客室タイプ）。この値は、Transaction（宿泊施設データ）メッセージ内の <RoomID> に対応します。最大 50 文字まで使用できます。
Promotions / HotelPromotions / Promotion / Stacking 0..1 Stacking プロモーションを組み合わせることができる方法を指定します。指定しない場合、「type」は base であると見なされます。
Promotions / HotelPromotions / Promotion / Stacking / @type 1 enum

この設定に応じて、1 つの料金に複数のプロモーションを適用できます。

  • any: 他のすべてのプロモーション（none を除く）と組み合わせることができますが、プロモーションの適用順序は保証されません。
  • base: 対象となる最適な base プロモーションが選択され、他のプロモーションよりも先に適用されます。以前は base_only という名前でした。
  • second: 最適な対象 second プロモーションが選択され、base プロモーション（該当する場合）の後に、any プロモーションの前に適用されます。
  • none: 他のプロモーションと組み合わせることはできません。

許可されている組み合わせの中で、割引が最大であるプロモーションのセットが料金に適用されます。
Promotions / HotelPromotions / Promotion / StayDates 0..1 StayDates 季節割引に対応するためなど、プロモーションの適用方法を決定する 1 つ以上の期間のコンテナ。
Promotions / HotelPromotions / Promotion / StayDates / @application 1 enum

プロモーションの適用方法を記述します。

指定できる値は次のとおりです。

  • all: 宿泊プランのすべての日付が滞在日と重複している場合、宿泊プランの 1 泊ごとにプロモーションを適用します。
  • any: 宿泊プランの任意の日付が滞在日の範囲にある日付と重複している場合、宿泊プランのすべての宿泊にプロモーションを適用します。
  • overlap: 滞在日の範囲にある日付と重複する宿泊プランの宿泊にのみプロモーションを適用します。

この属性は常に指定する必要があります。

  • <Discount> で percentage が指定されていて、application が all または any に設定されている場合、割引は滞在日全体の割合として適用されます。
  • <Discount> で percentage が指定されていて、application が overlap に設定されている場合、重複する宿泊に関して、宿泊料金の割合として割引が適用されます。
  • fixed_amount を指定する <Discount> と、overlap に設定された application は、無効な組み合わせです。
  • <FreeNights> はすべての application 値をサポートします。overlap の場合、割引の要件として考慮されるのは、重複する宿泊日数のみです。
Promotions / HotelPromotions / Promotion / StayDates / DateRange 1..99 DateRange

プロモーションを適用する日付を指定する期間。

YearlessDate 形式もサポートされています。

  • start または end のいずれかが年指定なしの日付になっている場合、どちらの日付も年指定なしの日付として入力する必要があります。
  • 年指定なしの期間は、新年をまたいで指定することはできません。代わりに、期間を 2 つの隣接する期間として表します。たとえば、{"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 ユーザーがプロモーションの対象となる国を 1 つ定義します。
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code 1 string CLDR 国コード（DE や FR など）。国によっては、CLDR 国コードが 2 文字の ISO 国コードと同じではないことに注意してください。また、CLDR 地域コードはサポートされていません。

例

宿泊施設あたりのプロモーション数の上限は 500 件です。宿泊施設からプロモーションを削除するには、「1 件のプロモーションを削除する」の例を参照してください。

基本的なメッセージ

次の例に基本的な 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>

1 件のプロモーションを削除する

次の例に、宿泊施設の 1 件のプロモーションを削除する方法を示します。

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


すべてのプロモーションをオーバーレイする

次の例は、1 つ以上の新しいプロモーションが含まれる宿泊施設の <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 種類のスタッキング

次の例は、3 つの異なるプロモーション（base、second、any）が適用される場合を示しています。他のプロモーションの方が割引率が高いため、none プロモーションは適用されません。元の価格が $100 の場合、割引価格は $72.90 になります。

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <Discount percentage="10"/>
      <Stacking type="base"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="10"/>
      <Stacking type="second"/>
    </Promotion>
    <Promotion id="3">
      <Discount percentage="10"/>
      <Stacking type="any"/>
    </Promotion>
    <Promotion id="4">
      <Discount percentage="25"/>
      <Stacking type="none"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

スタックタイプなし

次の例は、他のプロモーションを組み合わせると割引が小さくなるため、none プロモーションを使用する場合を示しています。元の価格が 100 ドルの場合、割引価格は 75 ドルになります。

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <Discount percentage="10"/>
      <Stacking type="base"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="10"/>
      <Stacking type="any"/>
    </Promotion>
    <Promotion id="3">
      <Discount percentage="25"/>
      <Stacking type="none"/>
    </Promotion>
  </HotelPromotions>
</Promotions>


予約可能期間の長さの範囲

次の例は、BookingWindow 要素が使用され、開始と終了の境界が ISO 8601 の Duration 型として定義されている場合を示しています。この予約可能期間の制限では、到着日の前日 18:00 までに予約し、到着日の 2 日前の 12:00 以降に予約する必要があります。

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

予約日時の上限と下限

次の例は、BookingDates 要素が start 属性と end 属性で DateTime 型として使用されている場合を示しています。この予約日付の制限では、2020 年 7 月 1 日 6 時 30 分から 2020 年 7 月 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 要素に、年のない start フィールドと end フィールドを持つ DateRanges が含まれているケースを示しています。この例では、プロモーションは年を問わず、12 月 29 日から 1 月 2 日までのチェックイン日付に適用されます。年指定なしの期間が新年の境界をまたぐ場合、その期間は無効になるため、DateRange は 2 つの隣接する期間として表現されます。

<?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 泊ごとに 2 泊を 50% 割引します。10 泊の旅行プランの場合、合計 4 泊が 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 泊ごとに 1 泊を 50% 割引します。割引の対象となるのは、重複する宿泊日数のみです。チェックイン日が 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>


ランク付けされた選択

次の例では、20% オフと 15% オフの 2 つの割引が提供されています。評価では、ランクが低いため、15% 割引のみが適用されます。

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <Discount percentage="15" rank="25"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="20" rank="50"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

BestDailyDiscount

次の例では、Discount とスタックされた BestDailyDiscount を適用して、2 泊の滞在を割引しています。

<?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 日までの 2 泊の宿泊を検討します。計算では、最も割引率の高い 1 泊あたりの割引の組み合わせが最初に見つかります。

1 泊目は「一般」プロモーションのみが対象で、割引率は 20% に固定されます。

2 泊目については、「5 月」プロモーションで「一般」割引よりも割引率が高くなっています。したがって、[may] が選択されている場合、固定割引額は 50 になります。

宿泊については、「fiesta」プロモーションにより 1 泊あたり 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 メッセージには、次の要素と属性があります。

要素 / @属性 発生回数 タイプ 説明
PromotionsResponse 1 Complex element 受信した Promotions Request メッセージの成功または問題を示すルート要素。
PromotionsResponse / @timestamp 1 DateTime このメッセージの作成日時。
PromotionsResponse / @id 1 string 関連する Promotions メッセージから得られる一意の識別子。
PromotionsResponse / @partner 1 string このメッセージのパートナー アカウント。
PromotionsResponse / Success 0..1 Success Promotions メッセージが正常に（警告、エラー、失敗が発生せずに）処理されたことを示します。

各メッセージには、<Success> と <Issues> のいずれかがあります。
PromotionsResponse / Issues 0..1 Issues Promotions メッセージの処理中に発生した 1 つ以上の問題のコンテナ。

各メッセージには、<Success> と <Issues> のいずれかがあります。
PromotionsResponse / Issues / Issue 1..n Issue Promotions メッセージの処理中に発生した警告、エラー、または失敗の説明。これらの問題の詳細については、フィード ステータスのエラー メッセージをご覧ください。
PromotionsResponse / Issues / Issue / @code 1 integer 問題の識別子。
PromotionsResponse / Issues / Issue / @status 1 enum

発生した問題の種類。

有効な値は warning、error、failure です。

例

成功

以下は、正常に処理された Promotions メッセージに対するレスポンスです。

<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
                    id="12345678"
                    partner="partner_key">
  <Success/>
</PromotionsResponse>

問題

以下は、エラーのため処理されなかった Promotions メッセージに対するレスポンスです。

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