Khuyến mãi

Tổng quan

API này cho phép bạn chỉ định các khoản chiết khấu có thể có. Trong số các chương trình khuyến mãi đã chỉ định, Google áp dụng chương trình khuyến mãi đủ điều kiện hoặc một nhóm các chương trình khuyến mãi đưa ra mức giá thấp nhất. Nếu bạn đang tìm một API hỗ trợ điều chỉnh mức giá tuỳ ý để có thể tăng hoặc giảm giá khi đáp ứng các điều kiện, hãy cân nhắc sử dụng API Sửa đổi giá. Xin lưu ý rằng nếu có cả hai API, thì các nội dung sửa đổi giá sẽ được áp dụng trước khi áp dụng chương trình khuyến mãi.

Yêu cầu

Cú pháp

Thông báo Promotions sử dụng cú pháp sau:

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

Phần tử và thuộc tính

Thông báo Chương trình khuyến mãi có các thành phần và thuộc tính sau:

Phần tử / @Thuộc tính Số lần xuất hiện Loại Nội dung mô tả
Promotions 1 Complex element Thành phần gốc của thông báo khuyến mãi.
Promotions / @partner 1 string Tài khoản đối tác dùng cho thư này. Giá trị của chuỗi này là giá trị của "Khoá đối tác" được liệt kê trên trang Cài đặt tài khoản trong Hotel Center.

Nếu bạn có một phần phụ trợ cung cấp nguồn cấp dữ liệu cho nhiều tài khoản, thì giá trị này cần phải khớp với giá trị thuộc tính ID được chỉ định trong phần tử <RequestorID> của thông báo <OTA_HotelRateAmountNotifRQ> và <OTA_HotelAvailNotifRQ> cho cùng một tài khoản.
Promotions / @id 1 string Giá trị nhận dạng duy nhất cho thông báo yêu cầu này. Giá trị này được trả về trong thông báo phản hồi. Các ký tự được phép là a-z, A-Z, 0-9, _ (dấu gạch dưới) và - (dấu gạch ngang).
Promotions / @timestamp 1 DateTime Ngày và giờ tạo thông báo này.
Promotions / HotelPromotions 0..n HotelPromotions

Chương trình khuyến mãi của cơ sở lưu trú. Mỗi chương trình khuyến mãi áp dụng cho một cơ sở lưu trú.

Trừ phi bạn sử dụng <Stacking>, chương trình khuyến mãi có mức chiết khấu cao nhất sẽ được áp dụng cho yêu cầu đặt trước khi có nhiều chương trình khuyến mãi đủ điều kiện.
Promotions / HotelPromotions / @hotel_id 1 string Giá trị nhận dạng duy nhất của cơ sở lưu trú. Giá trị này phải khớp với Mã khách sạn được chỉ định bằng phần tử <id> trong phần tử <listing> của Nguồn cấp dữ liệu danh sách khách sạn. Mã khách sạn cũng có trong Hotel Center.
Promotions / HotelPromotions / @action 0..1 enum

Nếu được chỉ định, giá trị này phải là "overlay". Khi giá trị là "overlay", mọi chương trình khuyến mãi đã lưu trữ sẽ bị xoá trước khi lưu trữ chương trình khuyến mãi được chỉ định trong thông báo hiện tại.

Nếu không được chỉ định, mỗi chương trình khuyến mãi được chỉ định trong thông báo hiện tại sẽ:

  • Added (nếu không có chương trình khuyến mãi đã lưu trữ nào có cùng id)
  • Updated (nếu chương trình khuyến mãi đã lưu trữ có cùng id)
  • Deleted (nếu chương trình khuyến mãi đã lưu trữ có cùng id và giá trị của thuộc tính action cho chương trình khuyến mãi được chỉ định trong thông báo hiện tại là "delete")
Promotions / HotelPromotions / Promotion 0..99 Promotion

Một chương trình khuyến mãi duy nhất cho một cơ sở lưu trú. Xin lưu ý rằng nếu bạn không chỉ định action="overlay" và <Promotion>, tất cả chương trình khuyến mãi cho cơ sở lưu trú này sẽ bị xoá.

Nếu bạn cần sử dụng hơn 99 chương trình khuyến mãi, hãy liên hệ với Nhà quản lý tài khoản hỗ trợ kỹ thuật (TAM).
Promotions / HotelPromotions / Promotion / @id 1 string Giá trị nhận dạng duy nhất của chương trình khuyến mãi. Số lượng ký tự tối đa được phép là 40. Các ký tự hợp lệ là a-z, A-Z, 0-9, _ (dấu gạch dưới), - (dấu gạch ngang) và . (dấu chấm).
Promotions /HotelPromotions / Promotion / @action 0..1 enum

Nếu được chỉ định, giá trị này phải là delete. Nếu bạn không chỉ định và không lưu trữ chương trình khuyến mãi có cùng id, thì chương trình khuyến mãi này sẽ được lưu trữ. Ngược lại, nếu bạn không chỉ định và chương trình khuyến mãi có cùng id được lưu trữ, thì chương trình khuyến mãi hiện có sẽ được cập nhật.

Nếu bạn chỉ định delete, chương trình khuyến mãi được lưu trữ có cùng id sẽ bị xoá. Khi sử dụng delete, không được thêm bất kỳ phần tử con nào vào <Promotion>. Ngoài ra, delete không được phép kết hợp với <HotelPromotions action="overlay"/>.
Promotions / HotelPromotions / Promotion / BookingDates 0..1 BookingDates Vùng chứa một hoặc nhiều phạm vi dùng để xác định thời điểm phải đặt phòng để được áp dụng chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange 1..99 DateRange Dải ô xác định thời điểm phải đặt phòng để được áp dụng chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start 0..1 Date hoặc DateTime

Ngày bắt đầu hoặc ngày giờ (dựa trên múi giờ của cơ sở lưu trú), tính cả phạm vi ngày.

  • Ngày hoặc ngày giờ do start chỉ định phải sớm hơn (hoặc giống với) ngày hoặc ngày giờ do end chỉ định.
  • Nếu bạn không chỉ định start, phạm vi sẽ có hiệu lực không giới hạn về thời gian bắt đầu.
  • Nếu start được điền sẵn là ngày "YYYY-MM-DD", thì ngày này sẽ được hiểu là ngày giờ "YYYY-MM-DDT00:00:00".
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end 0..1 Date hoặc DateTime

Ngày kết thúc hoặc ngày giờ (dựa trên múi giờ của cơ sở lưu trú), tính cả phạm vi ngày.

  • Ngày hoặc ngày giờ do end chỉ định phải sau (hoặc giống với) ngày hoặc ngày giờ do start chỉ định.
  • Nếu bạn không chỉ định end, phạm vi sẽ có hiệu lực không giới hạn về thời gian kết thúc.
  • Nếu end được cung cấp dưới dạng ngày "YYYY-MM-DD", thì ngày này sẽ được hiểu là ngày giờ "YYYY-MM-DDT23:59:59".
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week 0..1 string

Ngày trong tuần được phép sử dụng trong phạm vi ngày. Nếu bạn không chỉ định, tất cả các ngày đều được phép sử dụng trong phạm vi ngày. Mỗi ký tự trong chuỗi chỉ định một ngày. Ví dụ: "MTWHF" cho biết những ngày trong tuần được cho phép trong phạm vi ngày.

Các ký tự hợp lệ là:

  • M đại diện cho thứ Hai
  • T đại diện cho thứ Ba
  • W đại diện cho thứ Tư
  • H đại diện cho thứ Năm
  • F đại diện cho thứ Sáu
  • S đại diện cho thứ Bảy
  • U đại diện cho Chủ Nhật

Mọi tổ hợp ký tự đều hợp lệ.
Promotions / HotelPromotions / Promotion / BookingWindow 0..1 BookingWindow Cho biết khoảng thời gian mà việc đặt phòng phải diễn ra tương ứng với ngày nhận phòng (dựa trên múi giờ của cơ sở lưu trú). Ví dụ: Bạn có thể đặt thời hạn đặt trước là ít nhất 7 ngày, nhưng không được quá 180 ngày, trước ngày nhận phòng.
Promotions / HotelPromotions / Promotion / BookingWindow / @min 0..1 integer or duration Thời gian tối thiểu trước khi nhận phòng (khi khách phải đặt phòng) để được hưởng chương trình khuyến mãi. Nếu bạn không chỉ định thuộc tính này hoặc giá trị của thuộc tính này là 0, thì sẽ không có giá trị tối thiểu.

Các loại giá trị hợp lệ là:

  • Integer (Số nguyên): Số ngày trước ngày nhận phòng. Ví dụ: Giá trị 30 cho biết chương trình khuyến mãi chỉ áp dụng cho những lượt đặt phòng trước ngày nhận phòng ít nhất 30 ngày.
  • Thời lượng ISO 8601 (ngày, giờ và phút): Số ngày (và giờ/phút không bắt buộc) trước ngày nhận phòng. Ví dụ: Giá trị P30D cho biết chương trình khuyến mãi chỉ áp dụng cho những yêu cầu đặt phòng trước ngày nhận phòng ít nhất 30 ngày. Giá trị P30DT6H yêu cầu bạn phải đặt phòng vào hoặc trước 18:00 vào ngày thứ 30 trước khi đến nơi.
Promotions / HotelPromotions / Promotion / BookingWindow / @max 0..1 integer or duration Số ngày tối đa phải đặt phòng trước ngày nhận phòng để được hưởng chương trình khuyến mãi. Nếu bạn không chỉ định thuộc tính này hoặc giá trị của thuộc tính này là 0, thì sẽ không có giới hạn tối đa.

Các loại giá trị hợp lệ là:

  • Integer (Số nguyên): Số ngày trước ngày nhận phòng. Ví dụ: Giá trị 30 cho biết chương trình khuyến mãi chỉ áp dụng cho những lượt đặt phòng trước ngày nhận phòng tối đa 30 ngày.
  • Thời lượng ISO 8601 (ngày, giờ và phút): Số ngày (và giờ/phút không bắt buộc) trước ngày nhận phòng. Ví dụ: Giá trị P30D cho biết chương trình khuyến mãi chỉ áp dụng cho các yêu cầu đặt phòng trước ngày nhận phòng tối đa 30 ngày. Giá trị P30DT6H yêu cầu bạn phải đặt phòng vào hoặc sau 18:00 vào ngày thứ 30 trước khi đến.
Promotions / HotelPromotions / Promotion / Ceiling 0..1 Ceiling

Xác định các quy định hạn chế về giá trị tối đa mà một mức giá có thể được đặt sau khi áp dụng chương trình khuyến mãi.

Chương trình khuyến mãi phải luôn chỉ định <Discount> hoặc <BestDailyDiscount>. Vì vậy, để tạo chương trình khuyến mãi chỉ áp dụng <Ceiling>, bạn có thể đặt <Discount> bằng percentage của 0.

Nếu bạn định cấu hình xếp chồng, thì nhiều chương trình khuyến mãi có <Ceiling> có thể áp dụng cho một lượt lưu trú. Mỗi chương trình khuyến mãi sẽ áp dụng mức chiết khấu ngay sau đó. Ví dụ sau minh hoạ mức đóng góp của mỗi mức trần đối với tính toán chương trình khuyến mãi tiếp theo trong ngăn xếp.

Ví dụ:

Giá cho 1 đêm lưu trú, trong đó AmountBeforeTax là 100 và có một chồng gồm hai chương trình khuyến mãi:

  1. Chương trình khuyến mãi có loại xếp chồng base, fixed_amount là 25 và trần amount_per_night là 60
  2. Chương trình khuyến mãi có loại xếp chồng second, fixed_amount là 25 và trần amount_per_night là 90

Sau đây là thứ tự tính toán:

  1. Chương trình khuyến mãi base được áp dụng trước và giảm giá AmountBeforeTax xuống còn 75, sau đó mức trần sẽ giảm xuống còn 60.
  2. Chương trình khuyến mãi second giảm giá AmountBeforeTax từ 60 xuống còn 35. Giá trị này thấp hơn trần 90 nên không áp dụng trần thứ hai. Tỷ lệ cuối cùng là 35.

Trên thực tế, 60 là mức trần tổng thể nghiêm ngặt hơn không phù hợp vì nó chỉ hợp lệ với chương trình khuyến mãi của chính nó và không thể có mức trần duy nhất nào trải rộng toàn bộ ngăn xếp quảng cáo.
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night 1 float

Số tiền tối đa mà bạn có thể đặt mức giá mỗi đêm sau khi áp dụng chiết khấu.

Nếu cũng chỉ định một phần tử <Floor>, thì phần tử này phải được đặt thành một giá trị lớn hơn hoặc bằng thuộc tính amount_per_night trong <Floor>.

amount_per_night được áp dụng cho các khoản thuế và phí khi chúng được đưa vào giá mỗi đêm bằng AmountAfterTax, chứ không được áp dụng cho các khoản thuế và phí được chỉ định bằng TaxFeeInfo.
Promotions / HotelPromotions / Promotion / Floor 0..1 Floor

Xác định các quy định hạn chế về giá trị tối thiểu mà bạn có thể đặt sau khi áp dụng chương trình khuyến mãi.

Chương trình khuyến mãi phải luôn chỉ định <Discount> hoặc <BestDailyDiscount>. Vì vậy, để tạo chương trình khuyến mãi chỉ áp dụng <Floor>, bạn có thể đặt <Discount> bằng percentage của 0.

Logic <Floor> vẫn áp dụng cho các khoản chiết khấu <FreeNights>, ngay cả khi đêm miễn phí được áp dụng khoản chiết khấu 100%.

Nếu bạn định cấu hình xếp chồng, thì nhiều chương trình khuyến mãi có <Floor> có thể áp dụng cho một lượt lưu trú. Mỗi chương trình khuyến mãi sẽ áp dụng mức chiết khấu, ngay sau đó là giá sàn. Ví dụ sau minh hoạ cách mỗi sàn đóng góp vào việc tính toán chương trình khuyến mãi tiếp theo trong ngăn xếp.

Ví dụ:

Giá cho 1 đêm lưu trú, trong đó AmountBeforeTax là 100 và có một chồng gồm hai chương trình khuyến mãi:

  1. Chương trình khuyến mãi có loại xếp chồng base, fixed_amount là 25 và tầng amount_per_night là 90
  2. Chương trình khuyến mãi có loại xếp chồng second, fixed_amount là 25 và tầng amount_per_night là 60

Sau đây là thứ tự tính toán:

  1. Chương trình khuyến mãi base được áp dụng trước và chiết khấu AmountBeforeTax xuống còn 75, sau đó giá sàn sẽ tăng lên đến 90.
  2. Chương trình khuyến mãi second giảm giá AmountBeforeTax từ 90 xuống còn 65. Giá trị này cao hơn tầng 60 nên không áp dụng tầng thứ hai. Tỷ lệ cuối cùng là 65.

Trên thực tế, 90 là giá sàn tổng thể chặt chẽ hơn là không phù hợp vì giá trị này chỉ hợp lệ với chương trình khuyến mãi của chính nó và không có giá sàn nào trải dài toàn bộ ngăn xếp chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night 1 float

Số tiền tối thiểu mà bạn có thể đặt mức giá mỗi đêm sau khi áp dụng chiết khấu.

Nếu một phần tử <Ceiling> cũng được chỉ định, thì bạn phải đặt giá trị này thành một giá trị nhỏ hơn hoặc bằng thuộc tính amount_per_night trong <Ceiling>.

amount_per_night được áp dụng cho các khoản thuế và phí khi chúng được đưa vào giá mỗi đêm bằng AmountAfterTax, chứ không được áp dụng cho các khoản thuế và phí được chỉ định bằng TaxFeeInfo.
Promotions / HotelPromotions / Promotion / CheckinDates 0..1 CheckinDates Vùng chứa một hoặc nhiều phạm vi ngày dùng để xác định thời điểm phải nhận phòng để được áp dụng chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange 1..20 DateRange

Phạm vi ngày xác định thời điểm phải nhận phòng để được áp dụng chương trình khuyến mãi. Không bắt buộc phải sử dụng phần tử này nếu bạn đang xoá một hoặc nhiều chương trình khuyến mãi.

Định dạng YearlessDate cũng được hỗ trợ.

  • Nếu một trong hai giá trị start hoặc end là ngày không có năm, thì cả hai ngày này đều phải được điền là ngày không có năm.
  • Phạm vi ngày không theo năm không được bao quanh năm mới. Thay vào đó, hãy biểu thị phạm vi dưới dạng hai phạm vi ngày liền nhau. Ví dụ: {"12-29", "01-05"} có thể được biểu thị dưới dạng {"12-29", "12-31"} và {"01-01", "01-05"}.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @start 0..1 Date or YearlessDate Ngày bắt đầu (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trước hoặc giống với ngày end. Nếu bạn không chỉ định start, phạm vi ngày sẽ không có giới hạn về ngày bắt đầu.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end 0..1 Date or YearlessDate Ngày kết thúc (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trùng hoặc sau ngày start. Nếu bạn không chỉ định end, phạm vi ngày sẽ không có giới hạn đối với ngày kết thúc.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week 0..1 string

Ngày trong tuần được phép sử dụng trong phạm vi ngày. Nếu bạn không chỉ định, tất cả các ngày đều được phép sử dụng trong phạm vi ngày. Mỗi ký tự trong chuỗi chỉ định một ngày. Ví dụ: "MTWHF" cho biết những ngày trong tuần được cho phép trong phạm vi ngày.

Các ký tự hợp lệ là:

  • M đại diện cho thứ Hai
  • T đại diện cho thứ Ba
  • W đại diện cho thứ Tư
  • H đại diện cho thứ Năm
  • F đại diện cho thứ Sáu
  • S đại diện cho thứ Bảy
  • U đại diện cho Chủ Nhật

Mọi tổ hợp ký tự đều hợp lệ.
Promotions / HotelPromotions / Promotion / CheckoutDates 0..1 CheckoutDates Vùng chứa một hoặc nhiều phạm vi ngày dùng để xác định thời điểm phải trả phòng để được áp dụng chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange 1..20 DateRange

Phạm vi ngày xác định thời điểm phải trả phòng để được áp dụng chương trình khuyến mãi. Không bắt buộc phải sử dụng phần tử này nếu bạn đang xoá một hoặc nhiều chương trình khuyến mãi.

Định dạng YearlessDate cũng được hỗ trợ.

  • Nếu một trong hai start hoặc end là ngày không có năm, thì cả hai ngày này đều phải được điền dưới dạng ngày không có năm.
  • Phạm vi ngày không theo năm không được bao quanh năm mới. Thay vào đó, hãy biểu thị phạm vi dưới dạng hai phạm vi ngày liền nhau. Ví dụ: {"12-29", "01-05"} có thể được biểu thị dưới dạng {"12-29", "12-31"} và {"01-01", "01-05"}.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @start 0..1 Date or YearlessDate Ngày bắt đầu (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trước hoặc giống với ngày end. Nếu bạn không chỉ định start, phạm vi ngày sẽ không có giới hạn về ngày bắt đầu.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end 0..1 Date or YearlessDate Ngày kết thúc (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trùng hoặc sau ngày start. Nếu bạn không chỉ định end, phạm vi ngày sẽ không có giới hạn đối với ngày kết thúc.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @days_of_week 0..1 string

Ngày trong tuần được phép sử dụng trong phạm vi ngày. Nếu bạn không chỉ định, tất cả các ngày đều được phép sử dụng trong phạm vi ngày. Mỗi ký tự trong chuỗi chỉ định một ngày. Ví dụ: "MTWHF" cho biết những ngày trong tuần được cho phép trong phạm vi ngày.

Các ký tự hợp lệ là:

  • M đại diện cho thứ Hai
  • T đại diện cho thứ Ba
  • W đại diện cho thứ Tư
  • H đại diện cho thứ Năm
  • F đại diện cho thứ Sáu
  • S đại diện cho thứ Bảy
  • U đại diện cho Chủ Nhật

Mọi tổ hợp ký tự đều hợp lệ.
Promotions / HotelPromotions / Promotion / Devices 0..1 Devices Vùng chứa để liệt kê các thiết bị của người dùng đủ điều kiện tham gia chương trình khuyến mãi. Nếu xác định, chỉ những người dùng đủ điều kiện và đang sử dụng các thiết bị trong danh sách mới được hưởng mức giá chiết khấu. Nếu không xác định, người dùng đủ điều kiện và đang sử dụng bất kỳ thiết bị nào đều được hưởng mức giá chiết khấu.
Promotions / HotelPromotions / Promotion / Devices / Device 1..3 Device Xác định một loại thiết bị của người dùng đủ điều kiện tham gia chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / Devices / Device / @type 1 enum Một loại thiết bị. Giá trị phải là desktop, tablet hoặc mobile.
Promotions / HotelPromotions / Promotion / Discount 1 Discount

Bạn phải chỉ định chính xác một trong hai giá trị Discount hoặc BestDailyDiscount.

Cho biết mức chiết khấu sẽ áp dụng cho chương trình khuyến mãi này.
Promotions / HotelPromotions / Promotion / Discount / @percentage 0..1 float

Bạn phải cung cấp chính xác một trong các giá trị percentage, fixed_amount, fixed_amount_per_night, fixed_price hoặc fixed_price_per_night.

Một giá trị thập phân từ 0 đến 100 để xác định tỷ lệ chiết khấu theo phần trăm. Giá trị này được áp dụng cho AmountAfterTax (hoặc AmountBeforeTax nếu bạn không chỉ định AmountAfterTax).

Ví dụ:

  • Nếu AmountAfterTax là 100 và percentage là 20, thì

    tỷ lệ khuyến mãi = AmountAfterTax * (1 - tỷ lệ chiết khấu theo phần trăm)

    80 = 100 * (1 - 0,2)

  • Nếu AmountBeforeTax là 100, percentage là 20 và TaxFeeInfo cho biết thuế suất là 10, thì

    tỷ lệ khuyến mãi = AmountBeforeTax * (1 - tỷ lệ chiết khấu) + thuế

    90 = 100 * (1 - 0,2) + 10
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount 0..1 float

Bạn phải cung cấp chính xác một trong các giá trị percentage, fixed_amount, fixed_amount_per_night, fixed_price hoặc fixed_price_per_night.

Số tiền cố định sẽ được trừ vào tổng của đơn giá theo đêm AmountAfterTax (hoặc tổng của mức giá mỗi đêm AmountBeforeTax nếu không được chỉ định AmountAfterTax). Giá trị này được giả định là bằng cùng một đơn vị tiền tệ với đơn giá theo đêm. Nếu giá trị này lớn hơn tổng đơn giá theo đêm, thì giá trị thu được sẽ bằng 0.

Ví dụ:

  • Nếu chúng ta định giá 1 đêm lưu trú, trong đó AmountBeforeTax là 90, AmountAfterTax là 100 và fixed_amount là 20, thì

    tỷ lệ khuyến mãi = AmountAfterTax – mức chiết khấu cố định

    80 = 100 - 20

  • Nếu chúng ta định giá 1 đêm lưu trú, trong đó AmountBeforeTax là 100, fixed_amount là 20 và TaxFeeInfo cho biết mức thuế là 8%, thì

    tỷ lệ khuyến mãi = (AmountBeforeTax - mức chiết khấu cố định) * (1 + thuế theo tỷ lệ phần trăm)

    86,40 = (100 - 20) * 1,08

  • Nếu chúng ta định giá 1 đêm lưu trú, trong đó AmountBeforeTax là 50, fixed_amount là 60 và TaxFeeInfo cho biết thuế suất là 10, thì

    tỷ lệ khuyến mãi = (AmountBeforeTax - mức chiết khấu cố định) * thuế

    10 = 0 + 10

  • Nếu chúng ta định giá cho 3 đêm lưu trú, trong đó giá trị của AmountAfterTax là 100, 110 và 120; còn fixed_amount là 150, thì

    tỷ lệ khuyến mãi = tổng(AmountAfterTax) - (chiết khấu cố định)

    180 = (100 + 110 + 120) - 150
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night 0..1 float

Bạn phải cung cấp chính xác một trong các giá trị percentage, fixed_amount, fixed_amount_per_night, fixed_price hoặc fixed_price_per_night.

Một mức chiết khấu cố định được áp dụng cho từng mức giá mỗi đêm AmountAfterTax (hoặc N rẻ nhất nếu bạn chỉ định applied_nights). Nếu bạn không chỉ định AmountAfterTax, thì hệ thống sẽ áp dụng phương thức này cho AmountBeforeTax. Giá trị này được giả định là bằng cùng một đơn vị tiền tệ với đơn giá theo đêm. Nếu fixed_amount_per_night lớn hơn một mức giá theo đêm, thì mức giá theo đêm đó sẽ được giảm xuống bằng 0. Mức chiết khấu không thể làm cho mức giá mỗi đêm trở thành số âm.

Ví dụ:

  • Nếu chúng ta định giá cho 3 đêm lưu trú, trong đó giá trị của AmountAfterTax là 100, 110 và 120; còn fixed_amount_per_night là 10, thì

    tỷ lệ khuyến mãi = tổng(AmountBeforeTax – số tiền cố định được chiết khấu)

    300 = ((100 - 10) + (110 - 10) + (120 - 10))

  • Nếu chúng ta định giá cho 3 đêm lưu trú, trong đó giá trị của AmountAfterTax là 10, 50 và 100; còn fixed_amount_per_night là 20, thì

    tỷ lệ khuyến mãi = tổng(AmountAfterTax – số tiền cố định được chiết khấu)

    110 = (0 + (50 - 20) + (100 - 20))
Promotions / HotelPromotions / Promotion / Discount / @fixed_price 0..1 float

Bạn phải cung cấp chính xác một trong các giá trị percentage, fixed_amount, fixed_amount_per_night, fixed_price hoặc fixed_price_per_night.

Nếu bạn chỉ định giá mỗi đêm là AmountAfterTax, thì thuộc tính này sẽ đặt giá của lượt lưu trú (bao gồm cả thuế và phí) thành giá trị đã chỉ định. Nếu bạn chỉ định AmountBeforeTax, thì cho dù bạn có chỉ định AmountAfterTax hay không, giá trị này sẽ vẫn đặt giá trước thuế của lượt lưu trú thành giá trị đã chỉ định. Giá trị này được giả định là bằng cùng một đơn vị tiền tệ với đơn giá theo đêm.

Nếu mục đích của AmountAfterTax là để phản ánh một tỷ lệ phần trăm thuế, thì việc đặt một mức giá cố định cho AmountBeforeTax có thể dẫn đến việc thuế và phí không chính xác. Nhìn chung, bạn nên sử dụng TaxFeeInfo để chỉ định thuế và phí của một cơ sở lưu trú.

Ví dụ:

  • Nếu chúng ta định giá 1 đêm lưu trú, trong đó AmountBeforeTax là 90, AmountAfterTax là 100 và fixed_price là 80, thì giá khuyến mãi là 80.
  • Nếu chúng ta định giá 1 đêm lưu trú, trong đó AmountBeforeTax là 100, fixed_amount là 80 và TaxFeeInfo cho biết mức thuế là 8%, thì

    tỷ lệ khuyến mãi = giá cố định * (1 + thuế theo tỷ lệ phần trăm)

    86,40 = 80 * 1,08

  • Nếu chúng ta định giá cho 3 đêm lưu trú, trong đó giá trị của AmountAfterTax là 100, 110 và 120; còn fixed_amount là 300, thì

    tỷ lệ khuyến mãi = 300
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night 0..1 float

Bạn phải cung cấp chính xác một trong các giá trị percentage, fixed_amount, fixed_amount_per_night, fixed_price hoặc fixed_price_per_night.

Nếu bạn chỉ định giá mỗi đêm là AmountAfterTax, thì thuộc tính này sẽ đặt giá của mỗi đêm lưu trú (bao gồm cả thuế và phí) thành giá trị đã chỉ định. Nếu bạn chỉ định AmountBeforeTax, thì cho dù bạn có chỉ định AmountAfterTax hay không, thuộc tính này sẽ đặt giá trước thuế của mỗi đêm lưu trú thành giá trị đã chỉ định. Giá trị này được giả định là có cùng đơn vị tiền tệ với đơn giá mỗi đêm.

Nếu mục đích của AmountAfterTax là để phản ánh một tỷ lệ phần trăm thuế, thì việc đặt một mức giá cố định cho AmountBeforeTax có thể dẫn đến việc thuế và phí không chính xác. Nhìn chung, bạn nên sử dụng TaxFeeInfo để chỉ định thuế và phí của một cơ sở lưu trú.

Nếu bạn chỉ định applied_nights, giá mới sẽ được áp dụng cho N đêm rẻ nhất.

Ví dụ:

  • Nếu chúng ta định giá cho 2 đêm lưu trú, trong đó giá trị của AmountBeforeTax là 90, 90; giá trị của AmountAfterTax là 100, 100; và fixed_price là 80, thì tỷ lệ khuyến mãi sẽ là 80 + 80 = 160.
  • Nếu chúng ta định giá cho 2 đêm lưu trú, trong đó AmountBeforeTax là 100.100; fixed_amount là 80 và TaxFeeInfo cho biết thuế suất là 8%, thì tỷ lệ khuyến mãi sẽ là (80 + 80) * 1,08 = 172,8.
  • Nếu chúng ta định giá cho 3 đêm lưu trú, trong đó giá trị của AmountAfterTax là 100, 110 và 120; còn fixed_amount là 110, thì giá khuyến mãi sẽ là 110 * 3 = 330.
Promotions / HotelPromotions / Promotion / Discount / @applied_nights 0..1 integer

Bạn chỉ nên dùng thuộc tính này với percentage hoặc fixed_amount_per_night.

Số đêm được áp dụng chiết khấu, bắt đầu bằng đêm có giá thấp nhất. Phải là một số nguyên từ 1 đến 99. Nếu bạn không chỉ định, khoản chiết khấu sẽ được áp dụng cho tất cả các đêm.
Promotions / HotelPromotions / Promotion / Discount / FreeNights 0..1 FreeNights Xác định mức chiết khấu cho một số đêm lưu trú nhất định khi đáp ứng thời gian lưu trú tối thiểu. Bạn không được phép sử dụng các thuộc tính trên phần tử Discount mẹ nếu sử dụng phần tử này.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights 1 integer

Số đêm bắt buộc để áp dụng chiết khấu. Mỗi khoản chiết khấu sẽ được áp dụng cho một phân đoạn số đêm lưu trú riêng biệt.

Ví dụ: đối với thời gian lưu trú 10 đêm, trong đó stay_nights là 4 (và repeats là đúng), thì có 2 phân đoạn đêm lưu trú: đêm đầu tiên đến đêm thứ 4 và đêm thứ 5 đến đêm thứ 8; đêm thứ 9 và thứ 10 không thuộc phân đoạn đêm lưu trú.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights 1 integer Số đêm chiết khấu trong mỗi phân đoạn số đêm lưu trú.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage 1 float Khoản chiết khấu được áp dụng cho các đêm chiết khấu. Nếu giá trị này là 50, thì mỗi đêm bạn chọn sẽ được giảm 50%.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection 1 string Phải là cheapest hoặc last. Nếu là last, thì các đêm ở cuối phân đoạn số đêm lưu trú sẽ được chiết khấu. Nếu là cheapest, thì những đêm có giá rẻ nhất trong phân đoạn số đêm lưu trú sẽ được chiết khấu.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats 1 boolean

Liệu có thể áp dụng khoản chiết khấu cho những phân khúc đêm lưu trú nhiều lần hay không. Nếu là false, thì chỉ có phân đoạn số đêm lưu trú ở đầu hành trình mới được chiết khấu. Nếu giá trị là true, thì mọi phân đoạn số đêm lưu trú sẽ được chiết khấu.

Ví dụ: nếu stay_nights là 4 và hành trình là 10 đêm, thì nếu repeats là true, thì 2 chặng được giảm giá (đêm 1 đến đêm 4 và đêm 5 đến 8); nhưng nếu repeats là false, thì chỉ có 1 chặng được giảm giá (các đêm từ 1 đến 4).
Promotions / HotelPromotions / Promotion / Discount / @rank 0..1 integer Chỉ định một thứ hạng cho chương trình khuyến mãi này và đưa chương trình khuyến mãi đó vào lựa chọn theo thứ hạng, trong đó chỉ chương trình khuyến mãi có thứ hạng thấp nhất mới được chọn để áp dụng. Giá trị phải nằm trong khoảng từ 1 đến 99. Nếu nhiều chương trình khuyến mãi có cùng thứ hạng, thì một chương trình khuyến mãi sẽ được chọn và áp dụng tuỳ ý.
Promotions / HotelPromotions / Promotion / BestDailyDiscount 1 Discount

Bạn phải chỉ định chính xác một trong hai giá trị Discount hoặc BestDailyDiscount.

Xác định một khoản chiết khấu hằng ngày có thể áp dụng cho một đêm lưu trú. Điều này trái ngược với Discount, áp dụng chiết khấu cho toàn bộ thời gian lưu trú.

Mỗi cơ sở lưu trú có thể có một nhóm chương trình khuyến mãi duy nhất được coi là "tốt nhất hằng ngày". Điều này có nghĩa là đối với mỗi đêm lưu trú, chương trình khuyến mãi "tốt nhất hằng ngày" đủ điều kiện và mang lại mức chiết khấu cao nhất cho đêm đó sẽ được chọn và có thể được áp dụng.

Bạn không thể chỉ định Stacking bằng BestDailyDiscount. Các khoản chiết khấu "tốt nhất hằng ngày" mang lại mức chiết khấu cao nhất cho mỗi đêm được kết hợp và coi là chiết khấu cho một lượt lưu trú (tức là Discount) với kiểu xếp chồng được đặt thành base. Mức chiết khấu kết hợp này được so sánh và kết hợp với các chương trình khuyến mãi <Discount> đủ điều kiện khác để tìm ra ưu đãi hoặc tổ hợp chiết khấu sâu nhất. Hệ thống sẽ chọn và áp dụng tổ hợp BestDailyDiscount hoặc một Discount duy nhất, tuỳ vào mức nào tạo ra mức giá thấp hơn và áp dụng cho kiểu xếp chồng base.

Bạn có thể chỉ định StayDates bằng loại chiết khấu này, nhưng phải đặt application thành overlap

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

Bạn phải cung cấp chính xác một trong các giá trị percentage, fixed_amount hoặc fixed_price.

Một giá trị thập phân từ 0 đến 100 để xác định tỷ lệ chiết khấu theo phần trăm. Giá trị này được áp dụng cho AmountAfterTax (hoặc AmountBeforeTax nếu bạn không chỉ định AmountAfterTax).

Ví dụ:

  • Nếu AmountAfterTax cho một đêm lưu trú là 100 và percentage là 20, thì

    tỷ lệ khuyến mãi = AmountAfterTax * (1 - tỷ lệ chiết khấu theo phần trăm)

    80 = 100 * (1 - 0,2)

  • Nếu AmountBeforeTax đối với thời gian lưu trú là 100, percentage là 20 và TaxFeeInfo cho biết thuế suất là 10, thì

    tỷ lệ khuyến mãi = AmountBeforeTax * (1 - tỷ lệ chiết khấu) + thuế

    90 = 100 * (1 - 0,2) + 10
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount 0..1 float

Bạn phải cung cấp chính xác một trong các giá trị percentage, fixed_amount hoặc fixed_price.

Số tiền cố định sẽ được trừ vào một mức giá mỗi đêm AmountAfterTax (hoặc mức giá mỗi đêm AmountBeforeTax nếu bạn không chỉ định AmountAfterTax). Giá trị này được giả định là bằng cùng một đơn vị tiền tệ với đơn giá theo đêm. Nếu giá trị này lớn hơn tổng đơn giá theo đêm, thì giá trị thu được sẽ bằng 0.

Ví dụ:

  • Nếu AmountBeforeTax cho một đêm là 90, AmountAfterTax là 100 và fixed_amount là 20, thì

    tỷ lệ khuyến mãi = AmountAfterTax – mức chiết khấu cố định

    80 = 100 - 20

  • Nếu AmountBeforeTax cho một đêm là 100, fixed_amount là 20 và TaxFeeInfo cho biết mức thuế là 8%, thì

    tỷ lệ khuyến mãi = (AmountBeforeTax - mức chiết khấu cố định) * (1 + thuế theo tỷ lệ phần trăm)

    86,40 = (100 - 20) * 1,08
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price 0..1 float

Bạn phải cung cấp chính xác một trong các giá trị percentage, fixed_amount hoặc fixed_price.

Nếu bạn chỉ định giá mỗi đêm là AmountAfterTax, thì thuộc tính này sẽ đặt giá cho đêm lưu trú (bao gồm cả thuế và phí) thành giá trị đã chỉ định. Nếu bạn chỉ định AmountBeforeTax, thì cho dù bạn có chỉ định AmountAfterTax hay không, giá trị này sẽ vẫn đặt giá trước thuế của lượt lưu trú thành giá trị đã chỉ định. Giá trị này được giả định là bằng cùng một đơn vị tiền tệ với đơn giá theo đêm.

Ví dụ:

  • Nếu AmountBeforeTax cho một đêm là 90, AmountAfterTax là 100 và fixed_price là 80, thì tỷ lệ khuyến mãi là 80.
  • Nếu AmountBeforeTax cho một đêm là 100, fixed_amount là 80 và TaxFeeInfo cho biết mức thuế là 8%, thì

    tỷ lệ khuyến mãi = giá cố định * (1 + thuế theo tỷ lệ phần trăm)

    86,40 = 80 * 1,08
Promotions / HotelPromotions / Promotion / InventoryCount 0..1 InventoryCount Xác định các quy định hạn chế về số lượng phòng phải còn trống để được áp dụng chương trình khuyến mãi này. Chiết khấu chỉ được áp dụng cho những đêm đáp ứng quy định hạn chế. Không được áp dụng đối với khoản chiết khấu fixed_amount. Xin lưu ý rằng số lượng phòng trống sẽ được chỉ định bằng OTA_HotelInvCountNotifRQ (InvCount) hoặc OTA_HotelAvailNotifRQ (BookingLimit).
Promotions / HotelPromotions / Promotion / InventoryCount / @min 0..1 integer Số lượng phòng còn trống tối thiểu phải được dành ra cho chương trình khuyến mãi sẽ được áp dụng cho đơn giá theo đêm. Nếu bạn không xác định giá trị này, thì sẽ không có giá trị tối thiểu.
Promotions / HotelPromotions / Promotion / InventoryCount / @max 0..1 integer Số lượng phòng còn trống tối đa phải được dành ra cho chương trình khuyến mãi sẽ được áp dụng cho đơn giá theo đêm. Nếu bạn không xác định giá trị này, thì sẽ không có giới hạn tối đa.
Promotions / HotelPromotions / Promotion / LengthOfStay 0..1 LengthOfStay Xác định giới hạn thời gian lưu trú mà chương trình khuyến mãi có thể được áp dụng. Chương trình khuyến mãi không được áp dụng khi thời gian lưu trú nằm ngoài giới hạn tối thiểu và giới hạn tối đa.
Promotions / HotelPromotions / Promotion / LengthOfStay / @min 0..1 integer Số đêm tối thiểu trong thời gian lưu trú được phép áp dụng chương trình khuyến mãi. Nếu bạn không xác định giá trị này, thì sẽ không có giới hạn tối thiểu.
Promotions / HotelPromotions / Promotion / LengthOfStay / @max 0..1 integer Số đêm tối đa trong thời gian lưu trú được phép áp dụng chương trình khuyến mãi. Nếu bạn không xác định giá trị này, thì sẽ không có giới hạn tối đa.
Promotions / HotelPromotions / Promotion / MembershipRateRule 0..1 MembershipRateRule

Vùng chứa cho một quy tắc giá của thành viên kích hoạt một phiên bản giao diện người dùng cụ thể cho mức chiết khấu được liên kết.

Bạn không nên chỉ định phần tử này trừ phi bạn cũng chỉ định <Discount>.
Promotions / HotelPromotions / Promotion / MembershipRateRule / @id 1 string

Mã của quy tắc giá liên kết với một chương trình thành viên.
Promotions / HotelPromotions / Promotion / MinimumAmount 0..1 MinimumAmount Xác định tổng giá phòng tối thiểu của các ngày trong ngày (dùng AmountBeforeTax hoặc AmountAfterTax giá trị lớn hơn) mà bạn phải vượt quá để được áp dụng chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount 1 integer Bạn phải vượt quá giá trị này để được áp dụng chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / Occupancy 0..1 Occupancy Xác định các quy định hạn chế về số người lưu trú được áp dụng chương trình khuyến mãi này. Chương trình khuyến mãi không áp dụng khi số người lưu trú vượt quá giới hạn tối thiểu và tối đa.
Promotions / HotelPromotions / Promotion / Occupancy / @min 0..1 integer Số người lưu trú do người dùng chỉ định ít nhất phải là giá trị này thì mới được áp dụng chiết khấu.
Promotions / HotelPromotions / Promotion / Occupancy / @max 0..1 integer Số người lưu trú do người dùng chỉ định phải nằm trong giá trị tối đa này thì mới được áp dụng chiết khấu.
Promotions / HotelPromotions / Promotion / RatePlans 0..1 RatePlans Vùng chứa danh sách các gói giá được áp dụng chương trình khuyến mãi. Nếu bạn không chỉ định <RatePlans>, chương trình khuyến mãi sẽ áp dụng cho mọi gói giá.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan 1..n RatePlan Xác định một gói giá. Gói giá được xác định bằng tổ hợp gói, giá và tình trạng phòng, như xác định trong các thông báo Giao dịch (Dữ liệu của cơ sở lưu trú), OTA_HotelRateAmountNotifRQ và OTA_HotelAvailNotifRQ, và được xác định bằng PackageID.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id 1 string Giá trị nhận dạng riêng biệt của gói giá. Giá trị này liên kết với giá trị PackageID trong <PackageData> trong thông báo Giao dịch (Dữ liệu của cơ sở lưu trú) và trong thuộc tính RatePlanCode của <StatusApplicationControl> trong cả thông báo <OTA_HotelRateAmountNotifRQ> và <OTA_HotelAvailNotifRQ>. Số lượng ký tự tối đa được phép là 50.
Promotions / HotelPromotions / Promotion / RoomTypes 0..1 RoomTypes Vùng chứa danh sách các loại phòng được áp dụng chương trình khuyến mãi. Chương trình khuyến mãi sẽ được áp dụng cho từng <RoomType> được chỉ định. Nếu bạn không chỉ định <RoomTypes>, chương trình khuyến mãi sẽ áp dụng cho tất cả các phòng.
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType 1..n RoomType Xác định một loại phòng. Loại phòng được xác định trong phần tử <RoomData> của thông báo Giao dịch (Dữ liệu của cơ sở lưu trú) và được tham chiếu bằng giá trị <RoomID>. (Giá trị <RoomID> cũng được thuộc tính InvTypeCode trong các thông báo OTA_HotelRateAmountNotifRQ tham chiếu.)
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id 1 string Giá trị nhận dạng duy nhất của quỹ phòng (loại phòng). Giá trị này liên kết với <RoomID> trong thông báo Giao dịch (Dữ liệu của cơ sở lưu trú). Số lượng ký tự tối đa được phép là 50.
Promotions / HotelPromotions / Promotion / Stacking 0..1 Stacking Cho biết cách kết hợp các chương trình khuyến mãi. Nếu không được chỉ định, "type" sẽ được giả định là base.
Promotions / HotelPromotions / Promotion / Stacking / @type 1 enum

Bạn có thể áp dụng nhiều chương trình khuyến mãi cho một mức giá tuỳ thuộc vào chế độ cài đặt này:

  • any: Có thể kết hợp với bất kỳ chương trình khuyến mãi nào khác (ngoại trừ none). Tuy nhiên, chúng tôi không đảm bảo thứ tự áp dụng các chương trình khuyến mãi đó.
  • base: Chương trình khuyến mãi base đủ điều kiện nhất sẽ được chọn và áp dụng trước tiên, trước các chương trình khuyến mãi khác. Thuộc tính này trước đây có tên là base_only.
  • second: Chương trình khuyến mãi second đủ điều kiện nhất sẽ được chọn và áp dụng sau chương trình khuyến mãi base (nếu có) và trước chương trình khuyến mãi any.
  • none: Không thể kết hợp với các chương trình khuyến mãi khác.

Trong số các cách kết hợp được phép, tập hợp các chương trình khuyến mãi mang lại mức chiết khấu lớn nhất sẽ được áp dụng cho giá phòng.
Promotions / HotelPromotions / Promotion / StayDates 0..1 StayDates Vùng chứa một hoặc nhiều phạm vi ngày dùng để xác định cách áp dụng chương trình khuyến mãi, chẳng hạn như để phù hợp với các khoản chiết khấu theo mùa.
Promotions / HotelPromotions / Promotion / StayDates / @application 1 enum

Mô tả cách áp dụng chương trình khuyến mãi.

Các giá trị hợp lệ là:

  • all: Áp dụng chương trình khuyến mãi cho mỗi đêm trong hành trình nếu tất cả các ngày trong hành trình đó trùng với ngày lưu trú.
  • any: Áp dụng chương trình khuyến mãi cho tất cả các đêm trong hành trình nếu có bất kỳ ngày nào trong hành trình đó trùng lặp với một ngày trong phạm vi ngày lưu trú.
  • overlap: Chỉ áp dụng chương trình khuyến mãi cho những đêm trong hành trình trùng với một ngày trong phạm vi ngày lưu trú.

Thuộc tính này phải luôn được chỉ định.

  • Nếu <Discount> chỉ định percentage và application được đặt thành all hoặc any, thì khoản chiết khấu sẽ được áp dụng theo tỷ lệ phần trăm của toàn bộ thời gian lưu trú.
  • Nếu <Discount> chỉ định percentage và application được đặt thành overlap, thì mức chiết khấu sẽ được áp dụng theo tỷ lệ phần trăm giá mỗi đêm đối với các đêm bị trùng.
  • <Discount> chỉ định fixed_amount và application được đặt thành overlap là cách kết hợp không hợp lệ.
  • <FreeNights> hỗ trợ mọi giá trị application. Xin lưu ý rằng đối với overlap, các yêu cầu chiết khấu chỉ được cân nhắc đối với các đêm lưu trú trùng lặp.
Promotions / HotelPromotions / Promotion / StayDates / DateRange 1..99 DateRange

Phạm vi ngày xác định các ngày mà chương trình khuyến mãi sẽ được áp dụng.

Định dạng YearlessDate cũng được hỗ trợ.

  • Nếu một trong hai start hoặc end là ngày không có năm, thì cả hai ngày này đều phải được điền dưới dạng ngày không có năm.
  • Phạm vi ngày không theo năm không được bao quanh năm mới. Thay vào đó, hãy biểu thị phạm vi dưới dạng hai phạm vi ngày liền nhau. Ví dụ: {"12-29", "01-05"} có thể được biểu thị dưới dạng {"12-29", "12-31"} và {"01-01", "01-05"}.
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start 0..1 Date or YearlessDate Ngày bắt đầu (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trước hoặc giống với ngày end. Nếu bạn không chỉ định start, phạm vi ngày sẽ không có giới hạn về ngày bắt đầu.
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end 0..1 Date or YearlessDate Ngày kết thúc (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trùng hoặc sau ngày start. Nếu bạn không chỉ định end, phạm vi ngày sẽ không có giới hạn đối với ngày kết thúc.
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week 0..1 string

Ngày trong tuần được phép sử dụng trong phạm vi ngày. Nếu bạn không chỉ định, tất cả các ngày đều được phép sử dụng trong phạm vi ngày. Mỗi ký tự trong chuỗi chỉ định một ngày. Ví dụ: "MTWHF" cho biết những ngày trong tuần được cho phép trong phạm vi ngày.

Các ký tự hợp lệ là:

  • M đại diện cho thứ Hai
  • T đại diện cho thứ Ba
  • W đại diện cho thứ Tư
  • H đại diện cho thứ Năm
  • F đại diện cho thứ Sáu
  • S đại diện cho thứ Bảy
  • U đại diện cho Chủ Nhật

Mọi tổ hợp ký tự đều hợp lệ.
Promotions / HotelPromotions / Promotion / UserCountries 0..1 UserCountries Vùng chứa để liệt kê vị trí của người dùng (quốc gia) đủ điều kiện tham gia chương trình khuyến mãi. Nếu xác định, chỉ những người dùng đủ điều kiện ở các quốc gia được liệt kê mới được hưởng mức giá chiết khấu. Nếu không xác định, người dùng đủ điều kiện ở mọi quốc gia đều được hưởng mức giá chiết khấu.
Promotions / HotelPromotions / Promotion / UserCountries / @type 0..1 enum Loại thông số UserCountry.

Các giá trị hợp lệ là include và exclude.

Nếu bạn đặt type UserCountry là include, thì chương trình khuyến mãi sẽ áp dụng cho người dùng ở các quốc gia trong danh sách.

Nếu type UserCountry là exclude, thì chương trình khuyến mãi sẽ áp dụng cho người dùng ở bên ngoài các quốc gia được liệt kê.

Nếu bạn không đặt type UserCountry, thì thuộc tính này sẽ được coi là include và chương trình khuyến mãi sẽ được áp dụng cho người dùng ở các quốc gia trong danh sách.
Promotions / HotelPromotions / Promotion / UserCountries / Country 1..300 Country Xác định quốc gia nơi người dùng đủ điều kiện hưởng chương trình khuyến mãi.
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code 1 string Mã quốc gia CLDR, chẳng hạn như DE hoặc FR. Xin lưu ý rằng đối với một số quốc gia, mã quốc gia theo CLDR không giống với mã quốc gia gồm 2 chữ cái theo tiêu chuẩn ISO. Ngoài ra, mã vùng CLDR không được hỗ trợ.

Ví dụ

Thông báo cơ bản

Ví dụ sau đây trình bày một thông báo Promotions cơ bản:

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

Tình trạng quỹ phòng

Ví dụ sau đây cho thấy cách tạo chiết khấu nếu còn hàng thừa khi đã gần ngày đến:

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

Xoá một chương trình khuyến mãi

Ví dụ sau đây trình bày cách xoá một chương trình khuyến mãi của cơ sở lưu trú:

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

Xoá tất cả chiến dịch quảng bá

Ví dụ sau đây trình bày cách xoá tất cả chương trình khuyến mãi của một cơ sở lưu trú:

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


Phủ tất cả chương trình khuyến mãi

Ví dụ sau đây trình bày cách phủ <HotelPromotions> cho một cơ sở lưu trú có một hoặc nhiều chương trình khuyến mãi mới. Khi action="overlay", tất cả chương trình khuyến mãi đã lưu trữ sẽ bị xoá trước khi lưu trữ chương trình khuyến mãi được chỉ định trong thông báo hiện tại:

<?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 kiểu xếp chồng

Ví dụ sau đây cho thấy một trường hợp trong đó ba chương trình khuyến mãi khác nhau sẽ áp dụng (base, second, any). Xin lưu ý rằng chương trình khuyến mãi none sẽ không được áp dụng vì các chương trình khuyến mãi khác có mức chiết khấu tốt hơn. Nếu giá ban đầu là 100 USD thì giá chiết khấu sẽ là 72, 90 USD.

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

Không có kiểu xếp chồng

Ví dụ sau đây cho thấy một trường hợp trong đó chương trình khuyến mãi none được sử dụng vì sự kết hợp của các chương trình khuyến mãi khác cung cấp mức chiết khấu nhỏ hơn. Nếu giá ban đầu là 100 USD thì giá chiết khấu sẽ là 75 USD.

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


Giới hạn thời lượng đặt trước

Ví dụ sau đây cho thấy một trường hợp trong đó phần tử BookingWindow được sử dụng với giới hạn bắt đầu và giới hạn kết thúc được xác định là kiểu Thời lượng ISO 8601. Quy định hạn chế về thời hạn đặt phòng này yêu cầu bạn phải đặt phòng vào hoặc trước 18:00 của ngày trước khi đến và vào hoặc sau 12:00 của ngày thứ 2 trước khi đến.

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

Giới hạn ngày đặt phòng theo ngày giờ

Ví dụ sau đây cho thấy một trường hợp mà phần tử BookingDates được dùng với thuộc tính start và end làm loại DateTime. Quy định hạn chế về ngày đặt phòng này yêu cầu bạn phải đặt phòng trong khoảng thời gian từ 06:30 ngày 1 tháng 7 năm 2020 đến 18:45 ngày 2 tháng 7 năm 2020.

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

Phạm vi ngày không theo năm

Ví dụ sau đây cho thấy một trường hợp trong đó phần tử CheckInDates chứa DateRanges có trường start và end không có năm. Trong ví dụ này, chương trình khuyến mãi áp dụng cho ngày nhận phòng từ ngày 29/12 đến ngày 2/1, bất kể năm. Phạm vi ngày không theo năm vượt qua ranh giới năm mới là không hợp lệ, vì vậy, DateScope được biểu thị bằng hai phạm vi ngày liền kề.

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


Giảm giá FreeNights

Ví dụ sau đây chiết khấu 50% cho hai đêm mỗi 4 đêm lưu trú trong phạm vi ngày đặt phòng đã chỉ định. Đối với lịch trình 10 đêm, tổng cộng 4 đêm sẽ được giảm giá 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>

Ví dụ tiếp theo là chiết khấu 50% cho một đêm đối với mỗi ba đêm lưu trú trong phạm vi ngày lưu trú đã chỉ định. Chỉ các đêm lưu trú trùng lặp mới được tính vào đủ điều kiện hưởng chiết khấu. Đối với hành trình sau đây có ngày nhận phòng vào ngày 1 tháng 1 năm 2022 và ngày trả phòng vào ngày 7 tháng 1 năm 2022, số đêm lưu trú đủ điều kiện và khoản chiết khấu sẽ được áp dụng như sau.

  • 01-01-2022 (ở lại)
  • 2022-01-02 (ở lại)
  • 2022-01-03
  • 04/01/2022 (đã chiết khấu)
  • 05-01-2022 (ở lại)
  • 06-01-2022 (ở lại)
<?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>


Lựa chọn theo thứ hạng

Ví dụ sau đây đưa ra hai mức chiết khấu: một là giảm 20% và một là giảm 15%. Trong quá trình đánh giá, chỉ có chiết khấu 15% được áp dụng vì có thứ hạng thấp hơn.

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

Ví dụ sau đây chiết khấu thời gian lưu trú 2 đêm bằng cách áp dụng BestDailyDiscount xếp chồng cùng với 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>

Hãy cân nhắc lưu trú 2 đêm từ ngày 30 tháng 4 năm 2023 đến ngày 2 tháng 5 năm 2023. Để tính toán, trước tiên bạn sẽ tìm thấy tổ hợp các khoản chiết khấu hằng ngày hiệu quả nhất để có được mức chiết khấu sâu nhất.

Đối với đêm đầu tiên, chương trình khuyến mãi "chung" là số tiền duy nhất đủ điều kiện với mức chiết khấu cố định là 20.

Đối với đêm thứ hai, chương trình khuyến mãi "có thể" mang đến mức chiết khấu sâu hơn so với mức chiết khấu "chung". Vì vậy, khi chọn "có thể", số tiền chiết khấu cố định là 50.

Sau đó, đối với lượt lưu trú, chương trình khuyến mãi "fiesta" sẽ giảm giá còn 5 đêm mỗi đêm, tức là tổng cộng 10. Bạn có thể xếp chồng sự kiện này với tổ hợp các khoản chiết khấu hằng ngày tốt nhất vì "fiesta" có kiểu xếp chồng được đặt thành any. Nếu bạn đặt giá trị này thành base, thì chỉ tổ hợp chiết khấu tốt nhất hằng ngày hoặc chiết khấu "fiesta" mới được áp dụng. Hãy xem nội dung mô tả về Stacking để biết thêm thông tin.

"Nhìn chung, giá của lượt lưu trú sẽ được chiết khấu theo số tiền cố định là 20 + 50 + 10 = 80.

Phản hồi

Cú pháp

Thông báo PromotionsResponse sử dụng cú pháp sau:

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

Phần tử và thuộc tính

Thông báo PromotionsResponse có các phần tử và thuộc tính như sau:

Phần tử / @Thuộc tính Số lần xuất hiện Loại Nội dung mô tả
PromotionsResponse 1 Complex element Phần tử gốc cho biết thông báo yêu cầu Chương trình khuyến mãi nhận được thành công hay gặp vấn đề.
PromotionsResponse / @timestamp 1 DateTime Ngày và giờ tạo thông báo này.
PromotionsResponse / @id 1 string Giá trị nhận dạng duy nhất lấy từ thông báo Chương trình khuyến mãi được liên kết.
PromotionsResponse / @partner 1 string Tài khoản đối tác dùng cho thư này.
PromotionsResponse / Success 0..1 Success Cho biết rằng thông báo Chương trình khuyến mãi đã được xử lý thành công mà không có cảnh báo, lỗi hoặc lượt xử lý thất bại.

<Success> hoặc <Issues> xuất hiện trong mỗi thông báo.
PromotionsResponse / Issues 0..1 Issues Vùng chứa một hoặc nhiều vấn đề gặp phải trong quá trình xử lý thông báo Chương trình khuyến mãi.

<Success> hoặc <Issues> xuất hiện trong mỗi thông báo.
PromotionsResponse / Issues / Issue 1..n Issue Nội dung mô tả về cảnh báo, lỗi hoặc lỗi gặp phải trong quá trình xử lý thông báo Chương trình khuyến mãi. Bạn có thể xem thông tin chi tiết về các vấn đề này trong Thông báo lỗi về trạng thái nguồn cấp dữ liệu.
PromotionsResponse / Issues / Issue / @code 1 integer Giá trị nhận dạng của vấn đề.
PromotionsResponse / Issues / Issue / @status 1 enum

Loại vấn đề mà bạn gặp phải.

Các giá trị hợp lệ là warning, error và failure.

Ví dụ

Thành công

Dưới đây là phản hồi cho thông báo Chương trình khuyến mãi được xử lý thành công.

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

Vấn đề

Dưới đây là phản hồi cho một thông báo Chương trình khuyến mãi không được xử lý do lỗi.

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