ExtraGuestCharges

Overview

Rates sent through <OTA_HotelRateAmountNotifRQ> can be modified to account for adults and children in addition to the rate's original number of guests. The ExtraGuestCharges message allows specification for how rates should be calculated for these additional guests and for which rooms, rate plans, and stay dates their charges should apply.

Capacity Requirements

Prices calculated from the ExtraGuestCharges message are only valid if all capacity requirements are satisfied. See Transaction (Property Data) for more information.

Requests

Syntax

The ExtraGuestCharges message uses the following syntax:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges partner="partner_account_name"
                   id="message_ID"
                   timestamp="timestamp">
  <HotelExtraGuestCharges hotel_id="HotelID" action="[overlay]">
    <ExtraGuestCharge>
      <RatePlans>
        <RatePlan id="PackageID_1"/>
        <RatePlan id="PackageID_2"/>
      </RatePlans>
      <RoomTypes>
        <RoomType id="RoomID_1"/>
        <RoomType id="RoomID_2"/>
      </RoomTypes>
      <StayDates>
        <DateRange start="YYYY-MM-DD" end="YYYY-MM-DD"
                   days_of_week="MTWHFSU_or_subset"/>
      </StayDates>
      <AgeBrackets>
        <AdultCharge amount="float"/>
        <ChildAgeBrackets>
        <!-- The following are different ways child charges can be specified.
        Use the option that matches your system. -->
          <ChildAgeBracket max_age="integer" amount="float"
                           exclude_from_capacity="[true|false]"/>
          <ChildAgeBracket max_age="integer" percentage="float"
                           exclude_from_capacity="[true|false]"
                           counts_as_base_occupant="[never|preferred|always]"/>
          <ChildAgeBracket max_age="integer" discount_amount="float"
                           exclude_from_capacity="[true|false]"
                           counts_as_base_occupant="[never|preferred|always]"/>
        </ChildAgeBrackets>
      </AgeBrackets>
    </ExtraGuestCharge>
  </HotelExtraGuestCharges>
</ExtraGuestCharges>

Elements & Attributes

The ExtraGuestCharges message has the following elements and attributes:
Element / @Attribute Occurrences Type Description
ExtraGuestCharges 1 Complex element The root element of this message.
ExtraGuestCharges / @partner 1 String The partner account for this message. This string value is the "Partner key" value listed on the Account settings page in Hotel Center.

Note: If you have a backend that provides feeds for multiple accounts, this value needs to match the ID attribute value specified in the <RequestorID> element of your <OTA_HotelRateAmountNotifRQ> and <OTA_HotelAvailNotifRQ> messages for the same account.

ExtraGuestCharges / @id 1 String A unique identifier for this request message. This value is returned in the response message. Allowed characters are a-z, A-Z, 0-9, _ (underscore), and - (dash).
ExtraGuestCharges / @timestamp 1 DateTime The creation date and time of this message.
ExtraGuestCharges / HotelExtraGuestCharges 0..n HotelExtraGuestCharges Container for charges for a single property.
ExtraGuestCharges / HotelExtraGuestCharges / @hotel_id 1 String The unique identifier for the property. This value must match the Hotel ID specified using <id> in the <listing> element in the Hotel List Feed. The Hotel ID is also listed in Hotel Center.
ExtraGuestCharges / HotelExtraGuestCharges / @action 0..1 Enum Specifies how the update is applied. Only overlay is supported, and the default is overlay. Any previous charges for this property will be cleared before this update is applied.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge 0..99 ExtraGuestCharge

A single set of charges for a property. This may contain restrictions on how a charge may be applied and how charges are calculated by age or guest category.

Each ExtraGuestCharge within a HotelExtraGuestCharges must apply to a unique set of dates and products. If two ExtraGuestCharge elements refer to the same date-product combination, the entire message will be rejected.

ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets 1 AgeBrackets A container of age brackets that for calculating charges by age or guest category.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge 0..1 AdultCharge Container for the charge for an additional adult.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge / @amount 0..1 Float A non-negative decimal value which specifies the flat amount to be charged for an additional adult. This charge uses the same currency as the one specified for nightly rates.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets 0..1 ChildAgeBrackets Container for additional child charges. These age brackets may only cover the age range of 0-17 inclusive.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket 1..99 ChildAgeBracket A charge that applies to children in a specific age range. These should be ordered from lowest max_age to highest max_age. The amount to be charged can be specified via either amount, percentage, or discount_amount. Exactly one of those attributes must be specified for each <ChildAgeBracket>.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @max_age 1 Integer The maximum age for which the charges specified in <ChildAgeBracket> may apply. The minimum age is zero if there are no other <ChildAgeBracket> specified before this one. Otherwise it is one larger than the previous bracket's maximum age.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @exclude_from_capacity 1 Boolean A boolean that indicates whether a child in this age bracket should count towards a room's total capacity and child capacity. These capacities can be set with Transaction (Property Data). For example, infants below a certain age may not need to count towards the child capacity.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @amount 0..1 Float A non-negative decimal value which specifies the flat amount to be charged for an additional child in this bracket. This charge uses the same currency as the one specified for nightly rates.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @percentage 0..1 Float

A decimal value from 0-100 which specifies the percentage of an adult price that should be charged for an additional child in this bracket. This charge uses the same currency as the one specified for nightly rates.

See discussion under counts_as_base_occupant for details about how the adult price is calculated.

ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @discount_amount 0..1 Float

A non-negative decimal value which specifies a flat discount amount off the adult price for an additional child in this bracket. This charge uses the same currency as the one specified for nightly rates.

In general, the charge for a child in this bracket is calculated by deducting the flat amount from the "unit price". The unit price is discussed in more detail under the counts_as_base_occupant attribute section.

ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @counts_as_base_occupant 0..1 String

If the percentage or discount_amount attribute is specified, then counts_as_base_occupant must also be specified. This value determines whether or not a child should be included in the NumberOfGuest when we select a <BaseByGuestAmount> rate for applying percentage charges and discounts.

The goal here is to obtain a "unit price" from which the actual charge can be calculated.

unit price = rate / occupancy

The value of this attribute must be one of never, preferred, or always.

  • If never is specified then the child should never be included in the rate's occupancy.

    If we want to calculate a rate for 2 adults and 2 children (2+2), we'd use the rate for 2 adults because the children should not be included.

  • If preferred is specified then the child should preferably be included in the rate's occupancy.

    If we want to calculate a rate for 2 adults and 1 child (2+1), we'd preferably use the rate for 3 adults, but if that can't be found, then we'd use the rate for 2 adults.

  • If always is specified then the child should always be included in the rate's occupancy.

    If we want to calculate a rate for 2 adults and 2 children (2+2), we'd use the rate for 4 adults because the children must be included.

ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes 0..1 RoomTypes Container for a list of room types to which the charges apply. The charges are applied to each <RoomType> specified. If <RoomTypes> isn't specified, the charges apply to all rooms within the property specified.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType 1..n RoomType Specifies a room type. A room type is defined in a <RoomData> element in a Transaction (Property Data) message and is referenced using its <RoomID> value. (Its <RoomID> value is also referenced by the InvTypeCode attribute in OTA_HotelRateAmountNotifRQ messages.)
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType / @id 1 String The unique identifier for the inventory (room type). This value maps to <RoomID> in a Transaction (Property Data) message. The maximum number of characters allowed is 50.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans 0..1 RatePlans Container for a list of rate plans to which the charges apply. If <RatePlans> isn't specified, the charges applies to all rate plans.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan 1..n RatePlan Specifies a rate plan. A rate plan is defined by a combination of package, rates, and availability, as defined in Transaction (Property Data), OTA_HotelRateAmountNotifRQ, and OTA_HotelAvailNotifRQ messages, and as identified by the PackageID.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan / @id 1 String The unique identifier for the rate plan. This value maps to the PackageID value in <PackageData> in a Transaction (Property Data) message, and in the RatePlanCode attribute in <StatusApplicationControl> in both <OTA_HotelRateAmountNotifRQ> and <OTA_HotelAvailNotifRQ> messages. The maximum number of characters allowed is 50.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates 0..1 StayDates A container for one or more date ranges that determine how the charges are applied.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange 1..99 DateRange A date range specifying dates when the promotion is to be applied.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @start 0..1 Date The starting date (based on the property's time zone), inclusive, of the date range. This date must be before, or the same as, the end date. If start isn't specified, the date range is effectively unlimited in terms of a start date.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @end 0..1 Date The ending date (based on the property's time zone), inclusive, of the date range. This date must be the same as, or after, the start date. If end isn't specified, the date range is effectively unlimited in terms of an end date.
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @days_of_week 0..1 String

The days of the week that are allowed in the date range. If not specified, all days are allowed in the date range. Each character in the string specifies a day. For example, "MTWHF" specifies that weekdays are allowed in the date range.

Valid characters are:

  • M for Monday
  • T for Tuesday
  • W for Wednesday
  • H for Thursday
  • F for Friday
  • S for Saturday
  • U for Sunday

Any character combination is valid.

Examples

Adult Charges

Charges for additional adults can only be expressed as flat amounts.

The following example shows an ExtraGuestCharges message that specifies adult charges:

<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
  <HotelExtraGuestCharges hotel_id="ABC" action="overlay">
    <ExtraGuestCharge>
      <StayDates />
      <AgeBrackets>
        <AdultCharge amount="50" />
      </AgeBrackets>
    </ExtraGuestCharge>
  </HotelExtraGuestCharges>
</ExtraGuestCharges>

Here are the corresponding rates:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                            EchoToken="12345678"
                            TimeStamp="2020-05-19T20:50:37-05:00"
                            Version="3.0">
  <RateAmountMessages HotelCode="ABC">
    <RateAmountMessage>
      <StatusApplicationControl Start="2020-05-18"
                                End="2020-05-23"
                                InvTypeCode="RoomID_1"
                                RatePlanCode="PackageID_1"/>
      <Rates>
        <Rate>
          <BaseByGuestAmts>
            <BaseByGuestAmt AmountAfterTax="100.00"
                            CurrencyCode="USD"
                            NumberOfGuests="1"/>
            <BaseByGuestAmt AmountAfterTax="110.00"
                            CurrencyCode="USD"
                            NumberOfGuests="2"/>
            <BaseByGuestAmt AmountAfterTax="120.00"
                            CurrencyCode="USD"
                            NumberOfGuests="3"/>
          </BaseByGuestAmts>
        </Rate>
      </Rates>
    </RateAmountMessage>
  </RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>

When a user searches for four adults on Google, the total rate would be 170 = 120 + 50.

120 comes from the <BaseByGuestAmt> rate with NumberOfGuests="3" and 50 comes from the AdultCharge amount="50".

Child Charges

Charges for children are expressed in age brackets up to 17 and can be expressed in flat amounts, percentages, or discounts.

The following example shows an ExtraGuestCharges message that specifies child charges:

<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
  <HotelExtraGuestCharges hotel_id="ABC" action="overlay">
    <ExtraGuestCharge>
      <AgeBrackets>
        <ChildAgeBrackets>
          <ChildAgeBracket max_age="3" percentage="10"
                           counts_as_base_occupant="never" />
          <ChildAgeBracket max_age="10" percentage="30"
                           counts_as_base_occupant="preferred"/>
          <ChildAgeBracket max_age="17" discount_amount="10"
                           counts_as_base_occupant="always" />
        </ChildAgeBrackets>
      </AgeBrackets>
    </ExtraGuestCharge>
  </HotelExtraGuestCharges>
</ExtraGuestCharges>

Here are the corresponding rates:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                            EchoToken="12345678"
                            TimeStamp="2020-05-19T20:50:37-05:00"
                            Version="3.0">
  <RateAmountMessages HotelCode="ABC">
    <RateAmountMessage>
      <StatusApplicationControl Start="2020-05-18"
                                End="2020-05-23"
                                InvTypeCode="RoomID_1"
                                RatePlanCode="PackageID_1"/>
      <Rates>
        <Rate>
          <BaseByGuestAmts>
            <BaseByGuestAmt AmountAfterTax="100.00"
                            CurrencyCode="USD"
                            NumberOfGuests="1"/>
            <BaseByGuestAmt AmountAfterTax="110.00"
                            CurrencyCode="USD"
                            NumberOfGuests="2"/>
          </BaseByGuestAmts>
        </Rate>
      </Rates>
    </RateAmountMessage>
  </RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>
  1. Suppose we want the total price for 2 adults and 1 child of 2 years of age.

    Children aged 0-3 are never included in the rate's occupancy, so here we take the double occupancy rate and divide by 2 to get the unit price. Then we multiply by the percentage rate and sum with the rate to get the total price.

    unit price = 110 / 2 = 55

    total price = 110 + 55 * 0.1 = 115.5

  2. Suppose we want the total price for 1 adult and 2 children, both of 5 years of age.

    Children aged 4-10 are preferably included in the rate's occupancy. We start by looking for a 3 adult rate since both children are preferably included in the rate's occupancy. Since that doesn't exist, we fall back to the 2 adult rate. We take this rate and divide by two to get the unit price. Then we multiply by the percentage rate and sum with the scaled rate to get the total price.

    unit price = 110 / 2 = 55

    total price = 55 + 55 * 0.3 + 55 * 0.3 = 88

  3. Suppose we want the total price for 1 adult and 1 child of 17 years of age.

    Children aged 11-17 are always included in the rate's occupancy, so here we take the double occupancy rate and divide by 2 to get the unit price. Then we deduct by the discount amount and sum with the scaled rate to get the total price.

    unit price = 110 / 2 = 55

    total price = 55 + (55 - 10) = 100

Charge Restrictions

All types of restrictions are optional and any combination of them can be used.

The following example shows an ExtraGuestCharges message that specifies restrictions:

<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
  <HotelExtraGuestCharges hotel_id="ABC" action="overlay">
    <ExtraGuestCharge>
      <RoomTypes>
        <RoomType id="queen" />
        <RoomType id="king" />
      </RoomTypes>
      <RatePlans>
        <RatePlan id="free-wifi" />
        <RatePlan id="hot-breakfast" />
      </RatePlans>
      <StayDates>
        <DateRange start="2020-09-01" end="2020-09-14"/>
      </StayDates>
      <AgeBrackets>
        <AdultCharge amount="50" />
      </AgeBrackets>
    </ExtraGuestCharge>
  </HotelExtraGuestCharges>
</ExtraGuestCharges>

The message above specifies that adults should be charged for any product that has room type "queen" or "king" with rate plan "free-wifi" or "hot-breakfast" for the dates of September 1, 2020 to September 14, 2020.

Overlapping Charges

This section shows an example of an invalid message that specifies different charges for the same combinations of dates and products.

<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
  <HotelExtraGuestCharges hotel_id="ABC" action="overlay">
    <ExtraGuestCharge>
      <RoomTypes>
        <RoomType id="queen" />
      </RoomTypes>
      <RatePlans>
        <RatePlan id="free-wifi" />
      </RatePlans>
      <StayDates>
        <DateRange start="2020-09-01" end="2020-09-14"/>
      </StayDates>
      <AgeBrackets>
        <AdultCharge amount="50" />
      </AgeBrackets>
    </ExtraGuestCharge>
    <ExtraGuestCharge>
      <RoomTypes>
        <RoomType id="queen" />
        <RoomType id="king" />
      </RoomTypes>
      <RatePlans>
        <RatePlan id="free-wifi" />
        <RatePlan id="hot-breakfast" />
      </RatePlans>
      <StayDates>
        <DateRange start="2020-09-01" end="2020-09-05"/>
      </StayDates>
      <AgeBrackets>
        <AdultCharge amount="20" />
      </AgeBrackets>
    </ExtraGuestCharge>
  </HotelExtraGuestCharges>
</ExtraGuestCharges>

The message above is invalid because the first <ExtraGuestCharge> specifies that "queen" and "free-wifi" for September 1 to 14 should charge additional adults 50. The second <ExtraGuestCharge> specifies that any of "queen" or "king" with any of "free-wifi" or "hot-breakfast" for September 1 to 5 should charge additional adults 20. There are overlapping charges for "queen" and "free-wifi" for September 1 to 5 and a conflict between whether to charge 20 or 50 for an additional adult..

Responses

Syntax

The ExtraGuestChargesResponse message uses the following syntax:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="timestamp"
                    id="message_ID"
                    partner="partner_key">
  <!-- Either Success or Issues will be populated. -->
  <Success/>
  <Issues>
    <Issue code="issue_code" status="issue_type">issue_description</Issue>
  </Issues>
</ExtraGuestChargesResponse>

Elements & Attributes

The ExtraGuestChargesResponse message has the following elements and attributes:
Element / @Attribute Occurrences Type Description
ExtraGuestChargesResponse 1 Complex element The root element indicating the success or issues for a received ExtraGuestCharges request message.
ExtraGuestChargesResponse / @timestamp 1 DateTime The creation date and time of this message.
ExtraGuestChargesResponse / @id 1 String The unique identifier from the associated ExtraGuestCharges message.
ExtraGuestChargesResponse / @partner 1 String The partner account for this message.
ExtraGuestChargesResponse / Success 0..1 Success Indicates that the ExtraGuestCharges message was processed successfully without warnings, errors, or failures.

Either <Success> or <Issues> is present in each message.

ExtraGuestChargesResponse / Issues 0..1 Issues A container for one or more issues encountered while processing the ExtraGuestCharges message.

Either <Success> or <Issues> is present in each message.

ExtraGuestChargesResponse / Issues / Issue 1..n Issue The description of a warning, error, or failure encountered while processing the ExtraGuestCharges message. Details on these issues can be found in Feed Status Error Messages.
ExtraGuestChargesResponse / Issues / Issue / @code 1 Integer The identifier for the issue.
ExtraGuestChargesResponse / Issues / Issue / @status 1 Enum

The type of issue encountered.

Valid values are warning, error, and failure.

Examples

Success

The following is a response to a successfully processed ExtraGuestCharges message.

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

Issues

The following is a response to a ExtraGuestCharges message not processed due to errors.

<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="2020-05-18T16:20:00-04:00"
                    id="12345678"
                    partner="partner_key">
  <Issues>
    <Issue code="1001" status="error">Example</Issue>
  </Issues>
</ExtraGuestChargesResponse>