Rate Rules XML Reference

The rate rules XML file defines the rules for serving conditional rates and private rates. You can add or edit a rate rules XML file using the Rate rules page in Hotel Center. For more information about conditional rates and private rates, see Conditional and private rates.

Each rate rule requires an id, which can be referenced in a <Rate> of a Transaction message. A <Rate> that references a rate rule ID is only served to the users and under the conditions defined by the rate rule. A rate rule ID can also be referenced using a variable in a landing page URL.

<RateRuleSettings>

The root element of the rate rules XML file. The <RateRuleSettings> (formerly <PrivateRates>) element contains:

  • <UserRateCondition> elements that define the conditions to match on for conditional and private rates. For example, you can create a conditional rate that matches on the condition of all users in a certain country.

  • <RateRule> elements that each define a rate rule for reference in a <Rate> in a Transaction message. Each <RateRule> specifies the conditions and UI treatment that construct a conditional or private rate.

The <RateRuleSettings> element appears in the following place in the rate rules XML hierarchy:

+ <RateRuleSettings>
    + <UserRateCondition>
    + <RateRule>
        + <UserRateCondition>
        + <RateIneligibility>
        + <RateModification>

Syntax

The <RateRuleSettings> element uses the following syntax:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <UserRateCondition id="some_id" op="[all|any|none]">
    ...
  </UserRateCondition>
  <!-- Required -->
  <RateRule id="rate_rule_id">
    <!-- Required -->
    <UserRateCondition op="[all|any|none]">
      ...
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Attributes

The <RateRuleSettings> element doesn't have any attributes.

Child elements

The <RateRuleSettings> element has the following child elements:

Child Element Required? Type Description
<RateRule> Required <RateRule>

Defines the matching conditions, modifications, and eligibility for serving a conditional or private rate. Requires an id attribute, which can be referenced in a <Rate> of a Transaction message or in a landing page URL.

<UserRateCondition> Optional <UserRateCondition>

Defines one or more conditions that when matched result in conditional or private rates being served.

Conditions can be defined either inline by using <UserRateCondition> child elements, by reference to another <UserRateCondition> element by using the reference_id attribute, or both inline and by reference. However, any <UserRateCondition> with a reference_id must have 0 children.

A top-level <UserRateCondition> under <RateRuleSettings> must have an id attribute.

Conditional rates examples

The following examples show basic ways to define conditional rates.

Referencing predefined conditions, as shown in the Mobile users example, is recommended.

Mobile users

The following conditional rates example defines a rate rule that matches all mobile users by referencing a predefined <UserRateCondition>:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <UserRateCondition id="mobile">
    <UserDeviceType>mobile</UserDeviceType>
  </UserRateCondition>
  <RateRule id="mobile">
    <!-- Referencing pre-defined conditions is recommended -->
    <UserRateCondition reference_id="mobile"/>
  </RateRule>
</RateRuleSettings>

US users

The following conditional rates example defines a rate rule that matches all users searching in the US by referencing a predefined <UserRateCondition>:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <UserRateCondition id="us">
    <UserCountry>US</UserCountry>
  </UserRateCondition>
  <RateRule id="us">
    <UserRateCondition reference_id="us"/>
  </RateRule>
</RateRuleSettings>

<RateRule>

A container for specifying:

  • Conditions for serving a rate
  • Modifications, if any, to the price and UI treatment for the rate
  • Use of hidden UI treatments for private rates

The <RateRule> element appears in the following place in the rate rules XML hierarchy:

+ 
<RateRuleSettings>
    + <UserRateCondition>
    + <RateRule>
        + <UserRateCondition>
        + <RateIneligibility>
        + <RateModification>

Syntax

The <RateRule> element uses the following syntax:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings ...>
  <UserRateCondition ...>
  ...
  </UserRateCondition>
  <!-- At least one RateRule is required. The id attribute is required -->
  <RateRule id="rate_rule_id">
    <!-- One or more UserRateCondition elements (inline or referenced) are required. -->
    <UserRateCondition op="[all|any|none]"> // Inline example
      <Description>user_rate_condition_description</Description>
      <!-- Uses the member rate visible UI treatment -->
      <AlwaysEligibleMembershipProgram>program_name</AlwaysEligibleMembershipProgram>
      <LanguageCode>language_code</LanguageCode>
      <MaxUsersPercent>20</MaxUsersPercent> // 20% of users
      <!-- Requires <RateIneligibility> -->
      <MembershipProgram>program_name</MembershipProgram>
      <UserRateCondition reference_id="user_rate_condition_id"/>
      <UserCountry>country_code</UserCountry>
      <UserDeviceType>[mobile|desktop|tablet]</UserDeviceType>
      <UserListId>id</UserListId>
      <UserSignedIn>[true|false]</UserSignedIn>
      <IsDomestic>[true|false]</IsDomestic>
    </UserRateCondition>
    <RateIneligibility>
      <IneligibilityType>[exact|price_band|existence]</IneligibilityType>
      <IneligibilityReason>[program_member]</IneligibilityReason>
    </RateIneligibility>
    <RateModification>
      <HotelAmenity>[free_wifi]</HotelAmenity>
    </RateModification>
  </RateRule>
</RateRuleSettings>

Attributes

The <RateRule> element has the following attributes:

Attribute Required? Type Description
id Required string

A unique identifier for the rate rule. This ID is referenced using the rate_rule_id attribute of a <Rate> in a Transaction message to serve a conditional or private rate. The rate rule id can also be referenced using a variable and conditions in a landing page URL.

The maximum number of characters allowed is 40.

Child elements

The <RateRule> element has the following child elements:

Child Element Required? Type Description
<RateIneligibility> Optional <RateIneligibility> Specifies values that determine the specific UI treatment for a <MembershipProgram> rate.

Only valid when <MembershipProgram> is specified in <UserRateCondition>.

<UserRateCondition> Required <UserRateCondition>

Defines one or more conditions that when matched result in conditional or private rates being served.

Conditions can be defined either inline by using <UserRateCondition> child elements, by reference to another <UserRateCondition> by using the reference_id attribute, or both inline and by reference.

Note, however, that when a <UserRateCondition> is a child of <RateRule>, the <UserRateCondition> element cannot have an id attribute and cannot be referenced by another <UserRateCondition>.

<RateModification> Optional <RateModification> Modifies the UI treatment for private rates.
<PromoCode> Optional string Specifies a code to be associated with the rate if this rate rule is applied. Reflected in the PROMO-CODE landing page variable.

<UserRateCondition>

Defines one or more conditions that when matched result in conditional or private rates being served.

The <UserRateCondition> element appears in the following place in the rate rules XML hierarchy:

+ <RateRuleSettings>
    + <UserRateCondition>
    + <RateRule>
        + <UserRateCondition>
        + <RateIneligibility>
        + <RateModification>

Syntax

The <UserRateCondition> element uses the following syntax:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings ...>
  <!-- "op" is required for more than one child element -->
  <UserRateCondition id="some_id" op="[all|any|none]">
    <UserDeviceType>device_type</UserDeviceType>
  </UserRateCondition>
  <UserRateCondition id="some_other_id" op="[all|any|none]">
    <UserDeviceType>device_type</UserDeviceType>
  </UserRateCondition>
  <!-- At least one RateRule is required -->
  <RateRule id="rate_rule_id">
    <UserRateCondition reference_id="some_id"/>
  </RateRule>
  <RateRule id="rate_rule_id">
    <UserRateCondition reference_id="some_other_id"/>
  </RateRule>
  <RateRule id="rate_rule_id">
    <UserRateCondition>
      <UserDeviceType>device_type</UserDeviceType>
    </UserRateCondition>
  </RateRule>
<span class="nocode"></RateRuleSettings></span>

Attributes

The <UserRateCondition> element has the following attributes:

Attribute Required? Type Description
id Required (if top-level under <RateRuleSettings>) string

A unique identifier for this <UserRateCondition>. Can be referenced by a <RateRule> id attribute or by a <UserRateCondition> reference_id attribute.

op Optional enum

The op attribute is required when <UserRateCondition> has multiple child elements. The attribute value can be one of the following:

  • all: Include end-users that match all of the conditions defined by this rate rule. This value cannot be used when one of the conditions is <UserListId>, unless only one other condition—either <AlwaysEligibleMembershipProgram> or <MembershipProgram>—is defined.
  • any: Include end-users that match any of the conditions defined by this rate rule.
  • none: Exclude end-users that match any of the conditions defined by this rate rule. This value cannot be used when one of the conditions is <UserListId>.
reference_id Optional string

Defines this element as a reference to another predefined <UserRateCondition> with a matching id.

When reference_id is present:

  • Child elements are not be parsed
  • id and op shouldn't be present

Child elements

The <UserRateCondition> element has the following child elements:

Child Element Required? Type Description
<AlwaysEligibleMembershipProgram> Optional string

Specifies that the rate will use the member rate visible UI treatment.

The value of this element can be any membership program name.

<Description> Optional string Describes the <UserRateCondition>. This is for documentation purposes and has no effect on its capabilities.
<LanguageCode> Optional string Specifies that the rate will be offered to users whose language matches this two-letter language code.
<MaxUsersPercent> Optional float

Specifies that the rate will be offered randomly to this percentage of end users.

The value must be an integer between 0 and 100 (inclusive). For example, 20 will target 20% of end users.

<MembershipProgram> Optional string

Specifies that the rate will use a membership program UI treatment as determined by the <IneligibilityReason> of <RateIneligibility>.

For <MembershipProgram> to be valid, <RateIneligibility> must be specified.

The value of <MembershipProgram> can be any membership program name.

<UserRateCondition> Optional <UserRateCondition>

Defines one or more conditions that when matched result in conditional or private rates being served.

A <UserRateCondition> with a reference_id must have 0 children.

<UserCountry> Optional string

A CLDR country code, such as DE or FR. Note that, for some countries, the CLDR code isn't the same as the 2-letter ISO code. CLDR region codes are not supported.

Specifies that the user must be located in the specified country. Google determines the end-user's country from their IP address.

<UserDeviceType> Optional enum Defines the device type condition. Allowed values are:
  • mobile
  • desktop
  • tablet
<UserListId> Optional string The Google Ads user list ID of an audience list.

This condition can only be used with <AlwaysEligibleMembershipProgram> or <MembershipProgram>, or when op is any.

<UserSignedIn> Optional boolean A boolean that specifies whether or not the user must be signed in to their Google Account. A value of true indicates that the user must be signed in. A value of false indicates that the user must not be signed in. If you don't care whether the user is signed in or out, don't include a <UserSignedIn> condition.
<IsDomestic> Optional boolean A boolean that specifies whether or not the user must be from the same country where the hotel is located. A value of true indicates that the user must be from the same country as the hotel. A value of false indicates that the user may be from any country other than the hotel's country. If you want finer-grained control, use the <UserCountry> condition.

Conditional rates examples

Percentage of users

The following conditional rates example specifies that the rate will be offered randomly to twenty percent of the users:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="20_percent_users">
    <UserRateCondition>
      <MaxUsersPercent>20</MaxUsersPercent>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

UK and mobile users

The following conditional rates example defines a rate rule that matches all users searching in the United Kingdom with a mobile device by using an inline <UserRateCondition>:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="gb_mobile">
    <UserRateCondition op="all">
      <UserCountry>GB</UserCountry>
      <UserDeviceType>mobile</UserDeviceType>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Japan and not Japan

The following conditional rates example shows one rate rule that matches users in Japan and another rate rule that matches users in the rest of the world (RoW):

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="jp">
    <UserRateCondition>
      <UserCountry>jp</UserCountry>
    </UserRateCondition>
  </RateRule>
  <RateRule id="row_not_jp">
    <UserRateCondition op="none">
      <UserCountry>jp</UserCountry>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Any, all, and none

The following conditional rates example shows how the op attribute can be used to match on multiple conditions in different ways using the values any, all, and none. For example, as shown in the au_nz condition, you can use any to match users in any of several countries. As shown in the au_nz_mobile_tablet rate rule, you can use all to require that users match multiple conditions. The row_mobile_tablet rate rule will match users that are in the rest of the world (row), excluding Australia and New Zealand, and that also match the mobile_tablet condition.

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <UserRateCondition id="au_nz" op="any">
    <UserCountry>AU</UserCountry>
    <UserCountry>NZ</UserCountry>
  </UserRateCondition>
  <UserRateCondition id="mobile_tablet" op="any">
    <UserDeviceType>mobile</UserDeviceType>
    <UserDeviceType>tablet</UserDeviceType>
  </UserRateCondition>
  <RateRule id="au_nz_mobile_tablet">
    <UserRateCondition op="all">
      <UserRateCondition reference_id="au_nz"/>
      <UserRateCondition reference_id="mobile_tablet"/>
    </UserRateCondition>
  </RateRule>
  <RateRule id="row_mobile_tablet">
    <UserRateCondition op="all">
      <UserRateCondition op="none">
        <UserRateCondition reference_id="au_nz"/>
      </UserRateCondition>
      <UserRateCondition reference_id="mobile_tablet"/>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Private rates examples

Member rate visible 1

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="member_visible">
    <UserRateCondition>
      <AlwaysEligibleMembershipProgram>[enter your program here]</AlwaysEligibleMembershipProgram>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Member rate visible 2

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="member_visible_es_only">
    <UserRateCondition op="all">
      <AlwaysEligibleMembershipProgram>[enter your program here]</AlwaysEligibleMembershipProgram>
      <UserCountry>es</UserCountry>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Audience list rate 1

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="audience_list">
    <UserRateCondition>
      <UserListId>[enter an audience list id]</UserListId>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Audience list rate 2

This private rates example shows how to specify a member rate visible UI treatment for multiple audience lists:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="membership_program">
    <UserRateCondition op="all">
      <AlwaysEligibleMembershipProgram>[enter the program name here]</AlwaysEligibleMembershipProgram>
      <UserRateCondition op="any">
        <UserListId>[enter one audience list id here]</UserListId>
        <UserListId>[enter another audience list id here]</UserListId>
      </UserRateCondition>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

<RateIneligibility>

Indicates how to display the member rate hidden UI treatment. If not included, the member rate hidden UI treatment is not displayed.

To use <RateIneligibility> in a <RateRule>, <MembershipProgram> must also be specified in a <UserRateCondition> element for the <RateRule>.

The <RateIneligibility> element appears in the following place in the rate rules XML hierarchy:

+ 
<RateRuleSettings>
    + <UserRateCondition>
    + <RateRule>
        + <UserRateCondition>
        + <RateIneligibility>
        + <RateModification>

Syntax

The <RateIneligibility> element uses the following syntax:

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings ...>
  <UserRateCondition ...>
  ...
  </UserRateCondition>
  <RateRule ...>
    <UserRateCondition ...>
      ...
      <!-- Required when using RateIneligibility -->
      <MembershipProgram>program_name</MembershipProgram>
      ...
    </UserRateCondition>
    <RateIneligibility>
      <IneligibilityType>[exact|price_band|existence]</IneligibilityType>
      <IneligibilityReason>[program_member]</IneligibilityReason>
    </RateIneligibility>
  </RateRule>
</RateRuleSettings>

Attributes

The <RateIneligibility> element doesn't have any attributes.

Child elements

The <RateIneligibility> element has the following child elements:

Child Element Required? Type Description
<IneligibilityType> Required enum

Defines how the text (displayed next to the crossed-out rate) will describe the hidden rate.

Valid values are:

  • exact: A discount percentage. The text will read, "Get X% off with free enrollment."
  • price_band: A discount range. The text will read, "Get X-Y% off with free enrollment." For discounts of 1-5%, the text will read "Get up to 5% off." Larger discounts will be shown in 5-point increments, such as "Get 5-10% off" or "Get 10-15% off."
  • existence: A non-specific hint. In this case, the text will read: "Get a lower price with free enrollment."

Learn more about UI treatments in Private rates details and examples.

<IneligibilityReason> Required enum

Valid values are:

  • program_member: Displays the rate using the member rate hidden UI treatment.

Private rates examples

This section includes member rate hidden examples (basic) and member rate hidden examples (multiple conditions). You can also show your member rates to subsets of users. For examples, see Private rates examples.

Member rate hidden examples (basic)

Exact discount

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="membership_program">
    <RateIneligibility>
      <IneligibilityReason>program_member</IneligibilityReason>
      <IneligibilityType>exact</IneligibilityType>
    </RateIneligibility>
    <UserRateCondition>
      <MembershipProgram>[enter program name here]</MembershipProgram>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Band discount

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="membership_program">
    <RateIneligibility>
      <IneligibilityReason>program_member</IneligibilityReason>
      <IneligibilityType>price_band</IneligibilityType>
    </RateIneligibility>
    <UserRateCondition>
      <MembershipProgram>[enter program name here]</MembershipProgram>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Hint discount

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="membership_program">
    <RateIneligibility>
      <IneligibilityReason>program_member</IneligibilityReason>
      <IneligibilityType>existence</IneligibilityType>
    </RateIneligibility>
    <UserRateCondition>
      <MembershipProgram>[enter program name here]</MembershipProgram>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Member rate hidden examples (multiple conditions)

op="any"

Audience list rate for members + member rate hidden (existence discount) for non-members

This private rates example specifies the existence type of member rate hidden UI treatment, which will be shown to users and not to the audience list. Users in the audience list will see the audience rate.

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="membership_program">
    <RateIneligibility>
      <IneligibilityReason>program_member</IneligibilityReason>
      <IneligibilityType>existence</IneligibilityType>
    </RateIneligibility>
    <UserRateCondition op="any">
      <MembershipProgram>[enter program name here]</MembershipProgram>
      <UserListId>[enter you audience list id here]</UserListId>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

op="all"

Member rate hidden for audience list users only

This privates rate example specifies the exact type of member rate hidden UI treatment, modified with the additional text "plus free Wi-Fi". This UI treatment will be shown to users that match the audience list.

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="membership_program_for_audience_list">
    <RateIneligibility>
      <IneligibilityReason>program_member</IneligibilityReason>
      <IneligibilityType>exact</IneligibilityType>
    </RateIneligibility>
    <RateModification>
      <HotelAmenity>free_wifi</HotelAmenity>
    </RateModification>
    <UserRateCondition op="all">
      <MembershipProgram>[enter program name here]</MembershipProgram>
      <UserListId>[enter you audience list id here]</UserListId>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Transparent/visible UI

This example shows how to specify member rate with two UI treatments (transparent and visible UI) for users in the audience list and hidden rates for all other users.

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="membership_program">
    <RateIneligibility>
      <IneligibilityReason>program_member</IneligibilityReason>
      <IneligibilityType>existence</IneligibilityType>
    </RateIneligibility>
    <UserRateCondition op="any">
      <MembershipProgram>[enter program name here]</MembershipProgram>
      <UserRateCondition op="all">
        <UserListId>[enter you audience list id here]</UserListId>
        <AlwaysEligibleMembershipProgram>program_name</AlwaysEligibleMembershipProgram>
      </UserRateCondition>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

<RateModification>

Modifies the UI treatment for private rates.

The <RateModification> element appears in the following place in the rate rules XML hierarchy:

+ 
<RateRuleSettings>
    + <UserRateCondition>
    + <RateRule>
        + <UserRateCondition>
        + <RateIneligibility>
        + <RateModification>

Attributes

The <RateModification> element doesn't have any attributes.

Child elements

The <RateModification> element has the following child elements:

Child Element Required? Type Description
<HotelAmenity> Optional enum

Combine with <MembershipProgram> and <RateIneligibility> to modify the member rate hidden UI treatment.

Valid values are:

  • free_wifi: Adds plus free wifi to the text.
<PriceMultiplier> Optional float

Modifies the price by multiplying this value to the base rate, taxes, and fees. For example, if PriceMultiplier = 0.9, base rate = $100, taxes = $20, fees = $10; then after applying the multiplier: base rate = $90, taxes = $18, fees = $9.

This lets you apply a discount to all rates with a certain rate rule.

Private rates examples

Hotel amenity

Member rate hidden for all users (band discounts) + free wifi

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="membership_program">
    <RateIneligibility>
      <IneligibilityReason>program_member</IneligibilityReason>
      <IneligibilityType>price_band</IneligibilityType>
    </RateIneligibility>
    <RateModification>
      <HotelAmenity>free_wifi</HotelAmenity>
    </RateModification>
    <UserRateCondition>
      <MembershipProgram>[enter program name here]</MembershipProgram>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Price multiplier

Apply 5% discount to the mobile rates in the Price Feed

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="mobile">
    <RateModification>
      <PriceMultiplier>0.95</PriceMultiplier>
    </RateModification>
    <UserRateCondition>
      <UserDeviceType>mobile</UserDeviceType>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>