Overview
This API lets you define ways to dynamically apply actions to a rate whenever conditions are met, such as adjusting the price or enabling refundability. Unlike the Promotions API , which can only apply eligible promotions with the deepest discounts, this API applies any actions when certain conditions are met, including price adjustments that might ultimately increase the final price.
Requests
Syntax
The RateModifications
message uses the following syntax:
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModifications
partner=" partner_key
"
id=" message_ID
"
timestamp=" timestamp
">
<HotelRateModifications
hotel_id=" HotelID
"
action="[overlay]">
<ItineraryRateModification
id=" ModificationID
"
action="[delete]">
<BookingDates>
<DateRange
start="YYYY-MM-DD"
end="YYYY-MM-DD"
days_of_week=" "MTWHFSU_or_subset"
"/>
<DateRange
start="YYYY-MM-DD"
end="YYYY-MM-DD"
days_of_week=" "MTWHFSU_or_subset"
"/>
</BookingDates>
<BookingWindow
min=" integer
"
max=" integer
"/>
<CheckinDates>
<DateRange
start="YYYY-MM-DD"
end="YYYY-MM-DD"
days_of_week=" "MTWHFSU_or_subset"
"/>
</CheckinDates>
<CheckoutDates>
<DateRange
start="YYYY-MM-DD"
end="YYYY-MM-DD"
days_of_week=" "MTWHFSU_or_subset"
"/>
</CheckoutDates>
<Devices>
<Device
type="[desktop|tablet|mobile]"/>
</Devices>
<LengthOfStay
min=" integer
"
max=" integer
"/>
<MinimumAmount
before_discount=" integer
"/>
<RatePlans>
<RatePlan
id=" PackageID_1
"/>
<RatePlan
id=" PackageID_2
"/>
</RatePlans>
<RoomTypes>
<RoomType
id=" RoomID_1
"/>
<RoomType
id=" RoomID_2
"/>
</RoomTypes>
<StayDates
application="[all|any]">
<DateRange
start="YYYY-MM-DD"
end="YYYY-MM-DD"
days_of_week=" "MTWHFSU_or_subset"
"/>
</StayDates>
<UserCountries
type="[include|exclude]">
<Country
code=" country_code
"/>
</UserCountries>
<ModificationActions>
<PriceAdjustment
multiplier=" float
"/>
<RateRule
id=" RateRuleID
"/>
<Refundable
available=" [false|true]
"
refundable_until_days=" number_of_days
"
refundable_until_time=" time
"/>
<Availability
status=" [unavailable]
"/>
</ModificationActions>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
Elements and attributes
The RateModifications
message has the following elements and
attributes:
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.
Rate modifications for a property. Each rate modification applies to a single property.
Note:If multiple rate modifications can be applied to the same rate, all modifications are applied. No specific order is guaranteed.
<id>
in the <listing>
element
in the Hotel List Feed. The Hotel ID is also listed in Hotel Center
.If action
is not specified, then the modifications
within this element are added or updated for this hotel. If action="overlay"
is specified, then all previously defined
modifications for this hotel are first deleted. Then, the modifications
specified here are written. If action="overlay"
is used and
no modifications are specified within this element, then all
modifications for this hotel are deleted.
A single rate modification for a property.
Note: Rate modifications are difficult to debug and we recommend using them sparingly. Contact your Technical Account Manager (TAM) for use cases that require more than 200 rate modifications.
If not specified and a rate modification with the same id
isn't stored, then this rate modification is stored.
Otherwise, if not specified and a rate modification with the same id
is stored, then the existing rate modification is
updated.
If specified, the value must be "delete"
. If "delete"
is specified,
the stored rate modification with the same id
is deleted.
When using "delete"
, don't include any child elements in <ItineraryRateModification>
. Also, "delete"
is not
allowed in conjunction with <HotelRateModifications
action="overlay"/>
.
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:
-
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.
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:
-
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.
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:
-
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.
desktop
, tablet
, or mobile
.Action(s) which are applied to the rate if all specified conditions are met.
AmountBeforeTax
and AmountAfterTax
by the specified multiplierAmountBeforeTax
and AmountAfterTax
are
multiplied by this value.- The character limit for this field is 40 characters.
- Each rate may only be associated with a single rate rule.
- If there are multiple modifications applying a rate rule ID, the rate rule ID that is lexicographically smallest is assigned to the rate.
- If this ID does not match a rate rule in your rate rule definition file, it is considered ineligible.
When setting the attributes, note the following:
- This modification action fully rewrites a qualifying rate's Refundable setting, not just the populated fields.
- If
available
orrefundable_until_days
is not set, the rate does not display as refundable. - If
available
is0
orfalse
, the other attributes are ignored. The rate does not display as refundable even if one or both of the other attributes is set. - Setting
refundable_until_time
is recommended; if not set, the earliest time (midnight) is used.
1
or true
to indicate if the rate allows a full
refund; otherwise set to 0
or false
.available
is true
) Specifies
the number of days in advance of check-in that a full refund can be
requested. The value of refundable_until_days
must be an integer between 0 and 330, inclusive.available
is true
) Specifies
the latest time of day, in the local time of the hotel, that a full
refund request is honored. This can be combined with refundable_until_days
to specify, for
example, that "refunds are available until 4:00PM two days before
check-in". If refundable_until_time
isn't set, the value
defaults to midnight.unavailable
.status="unavailable"
, the rate is treated
as if it is unavailable, regardless of whether a valid price exists for
it.AmountBeforeTax
or AmountAfterTax
) that must
be exceeded for the rate modification to be applied.<RatePlans>
isn't specified, the rate
modification 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.<RoomType>
specified. If <RoomTypes>
isn't specified, the
rate modification applies to all rooms.<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.Describes how the rate modification should be applied.
Valid values are:
-
all
: Applies the rate modification to each night in the itinerary if alldates in the itinerary overlap with the stay dates. -
any
: Applies the rate modification to all nights in the itinerary if any date in the itinerary overlaps with a date in the stay dates range.
This attribute must always be specified.
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:
-
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.
Valid values are include
and exclude
.
If the UserCountries type
is set as include
, the rate modification applies to
users from the listed countries.
If the UserCountries type
is exclude
,
the rate modification applies to users outside the listed countries.
If the UserCountries type
is unset, it is treated as include
and the rate modification
applies to users from the listed countries.
DE
or FR
. Note that, for some
countries, the CLDR country code isn't the same as the 2-letter ISO
country code. Also, CLDR region codes are not supported.Examples
Basic message
The following example shows a basic RateModifications
` message:
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModifications
partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications
hotel_id="Property_1">
<ItineraryRateModification
id="1">
<BookingDates>
<DateRange
start="2023-07-01"
end="2023-07-31"
days_of_week="MTWHF"/>
<DateRange
start="2023-09-01"
end="2023-09-30"/>
</BookingDates>
<BookingWindow
min="7"
max="330"/>
<CheckinDates>
<DateRange
start="2023-10-01"
end="2023-10-31"
days_of_week="FSU"/>
</CheckinDates>
<CheckoutDates>
<DateRange
start="2023-10-08"
end="2023-11-07"
days_of_week="FSU"/>
</CheckoutDates>
<Devices>
<Device
type="mobile"/>
<Device
type="tablet"/>
</Devices>
<LengthOfStay
min="2"
max="14"/>
<RatePlans>
<RatePlan
id="234"/>
<RatePlan
id="567"/>
</RatePlans>
<RoomTypes>
<RoomType
id="123"/>
<RoomType
id="456"/>
</RoomTypes>
<UserCountries>
<Country
code="US"/>
<Country
code="GB"/>
</UserCountries>
<ModificationActions>
<PriceAdjustment
multiplier="1.2"/>
</ModificationActions>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
Delete one rate modification
The following example shows how to delete one rate modification for a property:
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModifications
partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications
hotel_id="Property_1">
<ItineraryRateModification
id="1"
action="delete"/>
</HotelRateModifications>
</RateModifications>
Delete all rate modifications
The following example shows how to delete all rate modifications for a property:
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModifications
partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications
hotel_id="Property_1"
action="overlay"/>
</RateModifications>
Overlay all rate modifications
The following example shows how to overlay <HotelRateModifications>
for
property with one or more new rate modifications. When action="overlay"
, all stored rate modifications are deleted prior to
storing the rate modifications specified in the current message:
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModifications
partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications
hotel_id="Property_1"
action="overlay"/>
<ItineraryRateModification
id="1">
<BookingDates>
<DateRange
start="2023-09-01"
end="2023-09-30"/>
</BookingDates>
<ModificationActions>
<PriceAdjustment
multiplier="1.2"/>
</ModificationActions>
<RoomTypes>
<RoomType
id="123"/>
<RoomType
id="456"/>
</RoomTypes>
<RatePlans>
<RatePlan
id="234"/>
<RatePlan
id="567"/>
</RatePlans>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
Multiple modification actions
The following example shows how to perform multiple modification actions at one time:
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModifications
partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications
hotel_id="Property_1">
<ItineraryRateModification
id="1">
<BookingDates>
<DateRange
start="2023-01-01"
end="2023-02-28"/>
</BookingDates>
<ModificationActions>
<PriceAdjustment
multiplier=".95"/>
<Refundable
available="true"
refundable_until_days="1"
refundable_until_time="12:00:00"/>
</ModificationActions>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
Turn off a rate plan for user countries
The following example shows how to limit a rate plan to only
Japanese ( JP
) users:
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModifications
partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications
hotel_id="Property_1">
<ItineraryRateModification
id="1">
<RatePlans>
<RatePlan
id="jp_only"/>
</RatePlans>
<UserCountries
type="exclude">
<Country
code="JP"/>
</UserCountries>
<ModificationActions>
<Availability
status="unavailable"/>
</ModificationActions>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
Responses
Syntax
The RateModificationsResponse
message uses the following syntax:
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModificationsResponse
timestamp=" timestamp
"
id=" message_ID
"
partner=" partner_key
">
<!--
Either
Success
or
Issues
will
be
populated.
-->
<Success/>
<Issues>
<Issue
code=" issue_code
"
status=" issue_type
"><var>issue_description</var></Issue>
</Issues>
</RateModificationsResponse>
Elements and attributes
The RateModificationsResponse
message has the following
elements and attributes:
Element / @Attribute | Occurrences | Type | Description |
---|---|---|---|
RateModifications
|
1 | Complex element | The root element indicating the success or issues for a received RateModifications request message. |
RateModificationsResponse / @timestamp
|
1 | DateTime | The creation date and time of this message. |
RateModificationsResponse / @id
|
1 | string | The unique identifier from the associated RateModifications message. |
RateModificationsResponse / @partner
|
1 | string | The partner account for this message. |
RateModificationsResponse / Success
|
0..1 | Success | Indicates that the RateModifications message was processed successfully
without warnings, errors, or failures. Either |
RateModificationsResponse / Issues
|
0..1 | Issues | A container for one or more issues encountered while processing the
RateModifications message. Either |
RateModificationsResponse / Issues / Issue
|
1..n | Issue | The description of a warning, error, or failure encountered while processing the RateModifications message. Details on these issues can be found in Feed Status Error Messages . |
RateModificationsResponse / Issues / Issue / @code
|
1 | integer | The identifier for the issue. |
RateModificationsResponse / Issues / Issue / @status
|
1 | enum | The type of issue encountered. Valid values are |
Examples
Success
The following is a response to a successfully processed RateModifications message.
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModificationsResponse
timestamp="2023-05-22T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</RateModificationsResponse>
Issues
The following is a response to a RateModifications message not processed due to errors.
<?xml
version="1.0"
encoding="UTF-8"?>
<RateModificationsResponse
timestamp="2023-05-22T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Issues>
<Issue
code="1001"
status="error">Example</Issue>
</Issues>
</RateModificationsResponse>