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:
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.
a-z
, A-Z
, 0-9
, _
(underscore), and -
(dash).<id>
in the <listing>
element
in the Hotel List Feed. The Hotel ID is also listed in Hotel Center
.overlay
is
supported, and the default is overlay. Any previous charges for this
property is cleared before the update is applied.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 is rejected.
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>
.<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.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 counts_as_base_occupant
for details
about how the adult price is calculated.
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 counts_as_base_occupant
attribute section.
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 you 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
neveris specified then the child should never be included in the rate's occupancy.If you want to calculate a rate for 2 adults and 2 children (2+2), you should use the rate for 2 adults because the children shouldn't be included.
-
If
preferredis specified then the child should preferably be included in the rate's occupancy.If you want to calculate a rate for 2 adults and 1 child (2+1), you should preferably use the rate for 3 adults, but if that can't be found, then you should use the rate for 2 adults.
-
If
alwaysis specified then the child should always be included in the rate's occupancy.If you want to calculate a rate for 2 adults and 2 children (2+2), you should use the rate for 4 adults because the children must be included.
<RoomType>
specified. If <RoomTypes>
isn't specified, the
charges apply to all rooms within the property specified.<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.)<RoomID>
in a Transaction (Property Data) message.
The maximum number of characters allowed is 50.<RatePlans>
isn't specified, the charges
applies to all rate plans.<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.end
date. If start
isn't specified, the date
range is effectively unlimited in terms of a start date.start
date. If end
isn't specified, the date
range is effectively unlimited in terms of an end date.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:
-
Mfor Monday -
Tfor Tuesday -
Wfor Wednesday -
Hfor Thursday -
Ffor Friday -
Sfor Saturday -
Ufor 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
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>
