概要
この API を使用すると、可能な割引を指定できます。指定したプロモーションの中から、最低価格につながる有効なプロモーションが適用されます。任意のレート調整をサポートする 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, fixed_amount, fixed_amount_per_night,
fixed_price, or fixed_price_per_night; applied_nights is only used
with percentage, fixed_amount_per_night, and fixed_price_per_night. -->
<Discount percentage="float" fixed_amount="float" fixed_amount_per_night="float"
fixed_price="float" fixed_price_per_night="float"
applied_nights="integer_1_to_99" rank="integer_1_to_99">
<!-- FreeNights may not be used in conjunction with attributes on Discount -->
<FreeNights stay_nights="integer" discount_nights="integer"
discount_percentage="float" night_selection="[cheapest|last]"
repeats="boolean"/>
</Discount>
<!-- Exactly one of Discount or BestDailyDiscount must be specified.
Specify only one of percentage, fixed_amount, or fixed_price. -->
<BestDailyDiscount percentage="float" fixed_amount="float" fixed_price="float"/>
<Devices>
<Device type="[desktop|tablet|mobile]"/>
</Devices>
<InventoryCount min="integer" max="integer"/>
<LengthOfStay min="integer" max="integer"/>
<MembershipRateRule id="RateRuleID"/>
<MinimumAmount before_discount="integer"/>
<Occupancy min="integer" max="integer"/>
<RatePlans>
<RatePlan id="PackageID_1"/>
<RatePlan id="PackageID_2"/>
</RatePlans>
<RoomTypes>
<RoomType id="RoomID_1"/>
<RoomType id="RoomID_2"/>
</RoomTypes>
<Stacking type="[any|base|none|second]"/>
<StayDates application="[all|any|overlap]">
<DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
</StayDates>
<UserCountries type="[include|exclude]">
<Country code="country_code"/>
</UserCountries>
</Promotion>
</HotelPromotions>
</Promotions>
要素と属性
プロモーション メッセージには次の要素と属性があります。
要素 / @Attribute | 発生回数 | タイプ | 説明 |
---|---|---|---|
Promotions | 1 | Complex element | プロモーション メッセージのルート要素。 |
Promotions / @partner | 1 | string | このメッセージのパートナー アカウント。この文字列値は、Hotel Center の
[アカウント設定] ページに表示される「パートナーキー」の値です。 複数のアカウントにフィードを提供するバックエンドがある場合、この値は、同じアカウントの |
Promotions / @id | 1 | string | このリクエスト メッセージの一意の識別子。この値はレスポンス メッセージで返されます。使用できる文字は、a ~ z、A ~ Z、0 ~ 9、_(アンダースコア)、-(ダッシュ)です。 |
Promotions / @timestamp | 1 | DateTime | このメッセージの作成日時。 |
Promotions / HotelPromotions | 0..n | HotelPromotions | 宿泊施設のプロモーション。各プロモーションは 1 つの宿泊施設に適用されます。
|
Promotions / HotelPromotions / @hotel_id | 1 | string | プロパティの一意の識別子。この値は、ホテルリスト フィードの
<listing> 要素の <id> を使用して指定されたホテル ID と一致する必要があります。ホテル ID は Hotel Center にも表示されます。 |
Promotions / HotelPromotions / @action | 0..1 | enum | 指定する場合、値は 指定しない場合、現在のメッセージで指定された各プロモーションは次のいずれかになります。
|
Promotions / HotelPromotions / Promotion | 0..99 | Promotion | 宿泊施設の 1 つのプロモーション。 99 個を超えるプロモーションを使用する必要がある場合は、テクニカル アカウント マネージャー(TAM)にお問い合わせください。 |
Promotions / HotelPromotions / Promotion / @id | 1 | string | プロモーションの一意の識別子。最大 40 文字まで使用できます。使用できる文字は、a ~ z、A ~ Z、0 ~ 9、_(アンダースコア)、-(ダッシュ)、.(ピリオド)キーを押します。 |
Promotions /HotelPromotions / Promotion / @action | 0..1 | enum | 指定する場合、値は
|
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 | 範囲の開始日または日時(プロパティのタイムゾーンに基づく)。
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end | 0..1 | Date または DateTime | 期間の終了日または日時(プロパティのタイムゾーンに基づく)。
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week | 0..1 | string | 期間で使用できる曜日。指定しなかった場合、期間内のすべての日付が許可されます。文字列の各文字で日付を指定します。たとえば、「MTWHF」は、日付範囲内で平日を許可することを指定します。 使用できる文字は次のとおりです。
任意の文字の組み合わせが有効です。 |
Promotions / HotelPromotions / Promotion / BookingWindow | 0..1 | BookingWindow | 予約が行われる期間を、チェックイン日を基準とする期間を指定します(宿泊施設のタイムゾーンが基準)。たとえば、予約期間は、チェックイン日の少なくとも 7 日間~ 180 日間に設定できます。 |
Promotions / HotelPromotions / Promotion / BookingWindow / @min | 0..1 | integer or duration | プロモーションが適用されるために予約が行われる必要があるチェックイン前の最小期間。これが指定されていない場合、または値が 0 の場合、最小値はありません。有効な値の型は次のとおりです。
|
Promotions / HotelPromotions / Promotion / BookingWindow / @max | 0..1 | integer or duration | プロモーションが適用されるために予約が発生する必要があるチェックインまでの最大日数。これが指定されていない場合、または値が 0 の場合、最大値はありません。有効な値の型は次のとおりです。
|
Promotions / HotelPromotions / Promotion / Ceiling | 0..1 | Ceiling |
プロモーションの適用後に料金を設定できる最大値に対する制限を定義します。 プロモーションでは常に 併用が設定されている場合、 例: 1 泊の料金で
計算の順序は次のとおりです。
60 はそれ自体のプロモーションに対してのみ有効であり、プロモーション スタック全体にまたがる単一の上限は設定できないため、60 は全体的により厳しい上限であるという事実は重要ではありません。 |
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night | 1 | float |
割引適用後に 1 泊料金に設定可能な最大金額。
|
Promotions / HotelPromotions / Promotion / Floor | 0..1 | Floor |
プロモーションの適用後に料金を設定できる最小値に関する制限を定義します。 プロモーションでは常に 1 泊無料に 併用が設定されている場合、 例: 1 泊の料金で
計算の順序は次のとおりです。
90 はそれ自体のプロモーションに対してのみ有効であり、プロモーション スタック全体にまたがる単一の最小価格は設定できないため、90 が全体的な最小価格よりも厳格であるという事実は重要ではありません。 |
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night | 1 | float |
割引適用後に 1 泊料金に設定可能な最小金額。
|
Promotions / HotelPromotions / Promotion / CheckinDates | 0..1 | CheckinDates | プロモーションを適用するには、チェックインが行われるタイミングを定義する 1 つ以上の期間のコンテナ。 |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange | 1..20 | DateRange | プロモーションが適用されるためにチェックインが発生するタイミングを指定する期間。プロモーションを削除する場合、この要素は必要ありません。 YearlessDate 形式もサポートされています。
|
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」は、日付範囲内で平日を許可することを指定します。 使用できる文字は次のとおりです。
任意の文字の組み合わせが有効です。 |
Promotions / HotelPromotions / Promotion / CheckoutDates | 0..1 | CheckoutDates | プロモーションを適用するには、チェックアウトのタイミングを定義する 1 つ以上の期間のコンテナを指定します。 |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange | 1..20 | DateRange | プロモーションが適用されるためにチェックアウトが必要となるタイミングを指定する期間。プロモーションを削除する場合、この要素は必要ありません。 YearlessDate 形式もサポートされています。
|
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」は、日付範囲内で平日を許可することを指定します。 使用できる文字は次のとおりです。
任意の文字の組み合わせが有効です。 |
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 |
このプロモーションに適用する割引を指定します。 |
Promotions / HotelPromotions / Promotion / Discount / @percentage | 0..1 | float |
割引率を指定する 0 ~ 100 の小数値。これは 例:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount | 0..1 | float |
例:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night | 0..1 | float |
例:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price | 0..1 | float |
例:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night | 0..1 | float |
例:
|
Promotions / HotelPromotions / Promotion / Discount / @applied_nights | 0..1 | integer |
割引が適用される泊数(料金の安いものから順)。1 ~ 99 の整数を指定する必要があります。指定しない場合、すべての宿泊に割引が適用されます。 |
Promotions / HotelPromotions / Promotion / Discount / FreeNights | 0..1 | FreeNights | 最小宿泊日数に達した場合に、特定の宿泊日数に対する割引を指定します。この要素が使用されている場合、親 Discount 要素の属性は使用できません。 |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights | 1 | integer | 割引の適用に必要な宿泊日数。各割引は宿泊日数の別のセグメントに適用されます。 たとえば、 |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights | 1 | integer | 滞在日数の各セグメントにおける割引後の宿泊数。 |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage | 1 | float | 割引の宿泊数に適用される割引。この値が 50 の場合、選択した 1 泊の料金は 50% 割引となります。 |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection | 1 | string | cheapest または last のいずれかを指定する必要があります。last の場合、滞在日数セグメントの終わりの泊数は割引されます。cheapest の場合、指定した宿泊日数のセグメント内で最も安い宿泊料金に割引が適用されます。 |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats | 1 | boolean | 複数の宿泊セグメントに割引を適用できるかどうか。 たとえば、 |
Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | このプロモーションにランクを割り当てて、ランク付けされた選択を有効にします。これにより、最もランクの低いプロモーションのみが選択されます。値は 1 ~ 99 にする必要があります。複数のプロモーションが同じランクを共有している場合は、いずれかが任意に選択されて適用されます。 |
Promotions / HotelPromotions / Promotion / BestDailyDiscount | 1 | Discount |
1 泊に適用される 1 日あたりの割引を指定します。これは、滞在全体に割引を適用する 宿泊施設ごとに、「毎日がおすすめ」と見なされるプロモーションのグループを 1 つ設定できます。つまり、1 泊ごとに、対象でその 1 泊で最も割引率が高い「毎日ベスト」プロモーションが 1 つ選択され、適用されます。
このタイプの割引では |
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage | 0..1 | float |
割引率を指定する 0 ~ 100 の小数値。これは 例:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount | 0..1 | float |
例:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price | 0..1 | float |
例:
|
Promotions / HotelPromotions / Promotion / InventoryCount | 0..1 | InventoryCount | このプロモーションを適用するために空いている必要がある客室の数に関する制限を定義します。割引は、制約を満たす宿泊にのみ適用されます。fixed_amount の割引では使用できません。利用可能な客室の数は、OTA_HotelInvCountNotifRQ(InvCount )または OTA_HotelAvailNotifRQ(BookingLimit )で指定します。 |
Promotions / HotelPromotions / Promotion / InventoryCount / @min | 0..1 | integer | プロモーションを 1 泊の料金に適用するために必要な客室の最小数。指定しない場合、最小値はありません。 |
Promotions / HotelPromotions / Promotion / InventoryCount / @max | 0..1 | integer | プロモーションを 1 泊の料金に適用するために必要な客室の最大数。指定しない場合、上限はありません。 |
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 処理をトリガーするメンバーシップ料金ルールのコンテナ。
|
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 | 料金プランの一意の識別子。この値は、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 つの料金に複数のプロモーションを適用できます。
許可される組み合わせの中で、割引率が最も大きいプロモーションのセットが料金に適用されます。 |
Promotions / HotelPromotions / Promotion / StayDates | 0..1 | StayDates | プロモーションの適用方法を決定する 1 つ以上の期間のコンテナ(季節性の割引に対応する場合など)。 |
Promotions / HotelPromotions / Promotion / StayDates / @application | 1 | enum | プロモーションの適用方法を記述します。 指定できる値は次のとおりです。
この属性は常に指定する必要があります。
|
Promotions / HotelPromotions / Promotion / StayDates / DateRange | 1..99 | DateRange | プロモーションが適用される日付を指定する期間。 YearlessDate 形式もサポートされています。
|
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start | 0..1 | Date or YearlessDate | 期間の開始日(プロパティのタイムゾーンに基づく)。この日付は、end と同じか、それ以前の日付にする必要があります。start が指定されていない場合、開始日に関しては、期間は実質的に無制限となります。 |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end | 0..1 | Date or YearlessDate | 期間の終了日(プロパティのタイムゾーンに基づく)。この日付は start と同じか、それ以降の日付にする必要があります。end が指定されていない場合、終了日は実質的に無制限となります。 |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week | 0..1 | string | 期間で使用できる曜日。指定しなかった場合、期間内のすべての日付が許可されます。文字列の各文字で日付を指定します。たとえば、「MTWHF」は、日付範囲内で平日を許可することを指定します。 使用できる文字は次のとおりです。
任意の文字の組み合わせが有効です。 |
Promotions / HotelPromotions / Promotion / UserCountries | 0..1 | UserCountries | プロモーションの対象となるユーザーの所在地(国)を一覧表示するコンテナ。指定すると、リストに含まれる国の対象ユーザーにのみ割引料金が提供されます。指定しなかった場合、どの国の対象ユーザーにも割引料金が適用されます。 |
Promotions / HotelPromotions / Promotion / UserCountries / @type | 0..1 | enum | UserCountry 仕様のタイプ。 有効な値は UserCountry Usercountry の UserCountry |
Promotions / HotelPromotions / Promotion / UserCountries / Country | 1..300 | Country | プロモーションの対象ユーザーを 1 つ定義します。 |
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code | 1 | string | CLDR 国コード(DE 、FR など)。一部の国では、CLDR 国コードが 2 文字の ISO 国コードと同じではありません。CLDR リージョン コードもサポートされていません。 |
例
基本的なメッセージ
次の例は、基本的な Promotions
メッセージを示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
id="123_abc"
timestamp="2020-05-18T16:20:00-04:00">
<HotelPromotions hotel_id="Property_1">
<Promotion id="1">
<BookingDates>
<DateRange start="2020-07-01" end="2020-07-31" days_of_week="MTWHF"/>
<DateRange start="2020-09-01" end="2020-09-30"/>
</BookingDates>
<BookingWindow min="7" max="330"/>
<CheckinDates>
<DateRange start="2020-10-01" end="2020-10-31" days_of_week="FSU"/>
</CheckinDates>
<CheckoutDates>
<DateRange start="2020-10-08" end="2020-11-07" days_of_week="FSU"/>
</CheckoutDates>
<Devices>
<Device type="mobile"/>
<Device type="tablet"/>
</Devices>
<Discount percentage="20" applied_nights="2"/>
<LengthOfStay min="2" max="14"/>
<RatePlans>
<RatePlan id="234"/>
<RatePlan id="567"/>
</RatePlans>
<RoomTypes>
<RoomType id="123"/>
<RoomType id="456"/>
</RoomTypes>
<Stacking type="base"/>
<UserCountries>
<Country code="US"/>
<Country code="GB"/>
</UserCountries>
</Promotion>
</HotelPromotions>
</Promotions>
在庫の状態
次の例は、入荷日近くに余剰在庫がある場合に割引を作成する方法を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
id="123_abc"
timestamp="2020-05-18T16:20:00-04:00">
<HotelPromotions hotel_id="Property_1">
<Promotion id="1">
<BookingWindow max="7"/>
<Discount percentage="10"/>
<InventoryCount min="3"/>
</Promotion>
</HotelPromotions>
</Promotions>
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>
予約日と日時の境界
次の例は、DateTime タイプとして start
属性と end
属性とともに BookingDates
要素を使用する場合を示しています。この予約日の制限では、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
要素に、年のない 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
と重ねて適用することで、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 泊目は「一般」プロモーションのみが、固定割引 20 割引の対象となる金額です。
2 泊目は、「5 月」プロモーションで「一般」割引よりも大きな割引が適用されます。たとえば、[可能性がある] を選択すると、固定割引額は 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
メッセージには次の要素と属性が含まれます。
要素 / @Attribute | 発生回数 | タイプ | 説明 |
---|---|---|---|
PromotionsResponse | 1 | Complex element | 受信したプロモーション リクエスト メッセージの成功または問題を示すルート要素。 |
PromotionsResponse / @timestamp | 1 | DateTime | このメッセージの作成日時。 |
PromotionsResponse / @id | 1 | string | 関連付けられている Promotions メッセージの一意の識別子。 |
PromotionsResponse / @partner | 1 | string | このメッセージのパートナー アカウント。 |
PromotionsResponse / Success | 0..1 | Success | Promotions メッセージが、警告、エラー、または失敗なく正常に処理されたことを示します。 各メッセージに |
PromotionsResponse / Issues | 0..1 | Issues | プロモーション メッセージの処理中に発生した 1 つ以上の問題のコンテナ。
各メッセージに |
PromotionsResponse / Issues / Issue | 1..n | Issue | プロモーション メッセージの処理中に発生した警告、エラー、エラーの説明。これらの問題について詳しくは、フィード ステータスのエラー メッセージをご覧ください。 |
PromotionsResponse / Issues / Issue / @code | 1 | integer | 問題の ID。 |
PromotionsResponse / Issues / Issue / @status | 1 | enum | 発生した問題の種類。 有効な値は |
例
完了
以下は、正常に処理されたプロモーション メッセージに対するレスポンスです。
<?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>