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 pre-defined 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 pre-defined <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 pre-defined <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>
      <GoogleOneMember>[true|false]</GoogleOneMember>
      <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>
    </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.

<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>
</RateRuleSettings>

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.
  • "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.
reference_id Optional String

Defines this element as a reference to another pre-defined <UserRateCondition> with a matching id.

When reference_id is present:

  • Child elements will not be parsed
  • id and op should not 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 functionality.
<GoogleOneMember> Optional Boolean When true, the rate is offered to Google One users.
<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

Specifies the two-letter country code (ISO 3166-1 alpha-2) for this country condition. For example, "US" or "DE".

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.
<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, do not include a <UserSignedIn> 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>

Google One rate

<?xml version="1.0" encoding="UTF-8"?>
<RateRuleSettings>
  <RateRule id="g1">
    <UserRateCondition>
      <GoogleOneMember>true</GoogleOneMember>
    </UserRateCondition>
  </RateRule>
</RateRuleSettings>

Audience list rate

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

<RateIneligibility>

Indicates how to display the member rate hidden UI treatment. If not included, the member rate hidden UI treatment will not be 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)

Example 1

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 any user that matches the membership program or the audience list.

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

Example 2

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 wifi". This UI treatment will be shown to users that match both the membership program and 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>

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

Private rates examples

Example 1

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>