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 |
| 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 is cleared before the 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 |
| 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 positive 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 using
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 1-99 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 |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @discount_amount | 0..1 | float | A positive 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 |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @counts_as_base_occupant | 0..1 | string | If the The goal here is to obtain a "unit price" from which the actual charge can be calculated.
The value of this attribute must be one of
|
| 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:
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 you 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 you should take the double occupancy rate and divide by 2 to
get the unit price. Then, 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
1. Suppose you 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. you should start by looking for a 3 adult rate since both
children are preferably included in the rate's occupancy. Since
that doesn't exist you should fall back to the 2 adult rate and then,
take this rate and divide by two to get the unit price. Finally,
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
1. Suppose you 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,
in this case, take the double occupancy rate and divide by 2 to get
the unit price. Then, deduct it 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 |
| ExtraGuestChargesResponse / Issues | 0..1 | Issues | A container for one or more issues encountered while processing the
ExtraGuestCharges message.
Either |
| 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 |
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>