Skip to content

OTA_HotelRateAmountNotifRQ

Method for sending room/rate level prices (RoomType/RatePlan combination) to Kurzurlaub.de.

We describe the OTA_HotelRateAmountNotifRQ Request (RQ) and Response (RS) using the example of the test hotel. The data is sent always via POST request.

OTA_HotelRateAmountNotifRQ - Request via POST

Endpoint for POST Request:

POST /ota/api/HotelRateAmountNotif

Parameters used

Authentication and hotel parameters:

  • @AgentDutyCode - Agent ID: (optional specification - test agent = 1)
  • RequestorID@ID - Hotel ID: (TestHotel = 4)
  • RateAmountMessages@HotelCode - Hotel ID / HotelCode: (TestHotel 4)

Period, room and rate parameters:

A room ID + offer and a period (date from/to) are expected as RateAmountMessage

  • @Start - Date (DateFormat YYYY-MM-DD)
  • @End - Date (DateFormat YYYY-MM-DD)
  • @InvTypeCode - room ID or alternatively @InvCode possible
  • @RatePlanCode - offer ID / code or alternatively @RatePlanID possible

Examples: 

<StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-12-24" End="2023-12-31"/>
<StatusApplicationControl InvTypeCode="9143" RatePlanCode="TEST-BAR" Start="2023-12-24" End="2023-12-31"/>
<StatusApplicationControl InvCode="9143" RatePlanID="20540" Start="2023-12-24" End="2023-12-31"/>

Parameters for prices:

  • @AmountAfterTax - price (value >= 0)
  • @NumberOfGuests - number of guests in the room (value > 0) e.g. 1 person in a single room, 2 people in a double room
  • @AgeQualifyingCode - price for adults or children
    • Rate for adults in room AgeQualifyingCode="10"
    • Price for children AgeQualifyingCode="8" (currently ignored)

Example:

<BaseByGuestAmts>
    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="155.99" />
    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="125.99" />
    <BaseByGuestAmt AgeQualifyingCode="8" AmountAfterTax="15.99" />
</BaseByGuestAmts>

Note: unless the number of people in the room matches the NumberOfGuests attribute, the price will be ignored. In a double room (occupancy with 2 people) only the price NumberOfGuests="2" is considered, a single occupancy with a different price is not possible.

Alternative parameters:

  • @RatePlanCode - String for offer code (RatePlanCode="TEST-BAR" or ID RatePlanCode="20540")
  • @RatePlanID - Integer for offer ID (RatePlanID ="20540")

By using the parameters @RatePlanCode or @RatePlanID the Prices processed at room and offer level in combination.

The @RatePlanCode can either be a string (BEST-BAR) or alternatively an offer ID (integer value) to be sent. The rate code can be stored in the Kurzurlaub.de backend of the hotelier for each offer, to map offers and rates in the OTA backend or hotel software better and more clearly.

A notice:

  • we are currently ignoring various BookingRules (e.g. LengthOfStay, CloseToArrival CTA, CloseToDeparture CTD, Close)

Validation of incoming data

Validation of incoming parameters for date range (date from/to):

  • a valid DatePeriod (@Start - @End)
  • a valid date format (YYYY-MM-DD)
  • not in the past
  • no more than 2 years in advance
  • no more than 3 months as a continuous period

Validation of other parameters:

  • no more than 4000 lines per request
  • price - as float >= 0 (AmountAfterTax="125.90" or AmountAfterTax="12590" DecimalPlaces="2")
  • Room ID valid and room is online/active
  • Room ID and Offer ID are valid in combination and offer is online / active

Notice:

The data sent by the OTA partner will only be accepted for rooms that are *active and online*, alternatively warnings will be sent in response.

In general, lines with RateAmountMessage are considered individually, i.e. an error in the InvTypeCode or in the date format, date range is only sent as a warning for this one line. All other lines are processed independently.

For example, each message contains a StatusApplicationControl element for a room/offer from a hotel (RequestorID@ID).

Sample request

Example OTA_HotelRateAmountNotifRQ Request to send room and offer level prices with used attributes @RatePlanID or @RatePlanCode

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" TimeStamp="2022-12-01T09:30:47+08:00" Version="1.0" EchoToken="abc123">
<RateAmountMessages HotelCode="4">
    <!-- Invalid RatePlanCode (TEST-BAR) or InvTypeCode (2625) not allowed within this rate-->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="2625" RatePlanCode="TEST-BARS" Start="2022-12-26" End="2022-12-27"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="155.99" />
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="125.99" />
                    <BaseByGuestAmt AgeQualifyingCode="8" AmountAfterTax="15.99" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <!-- Error: Invalid start date (2022-12-18) is in past -->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-05-18" End="2023-05-21"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>   
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="3895" DecimalPlaces="2" />
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="4995" DecimalPlaces="2" />
                    <BaseByGuestAmt NumberOfGuests="3" AgeQualifyingCode="10" AmountAfterTax="5995" DecimalPlaces="2" />
                </BaseByGuestAmts>
                <AdditionalGuestAmounts>
                    <AdditionalGuestAmount Amount="1000" DecimalPlaces="2" />
                </AdditionalGuestAmounts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <!-- Doppelzimmer - NumberOfGuests="2" -->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="431721" Start="2023-05-18" End="2023-05-21"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="5996" DecimalPlaces="2" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <!-- Einzelzimmer - NumberOfGuests=1  -->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="5307" RatePlanCode="431721" Start="2023-05-16" End="2023-05-21"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="4450" DecimalPlaces="2" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>

    <!-- Invalid RatePlanCode (TEST-BAR) or InvTypeCode (2625) not allowed within this rate-->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="2625" RatePlanCode="TEST-BAR" Start="2022-12-16" End="2022-12-17"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt AgeQualifyingCode="10" AmountAfterTax="125.50"/>
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="TEST-BAR" Start="2022-12-28" End="2022-12-29"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt AgeQualifyingCode="10" AmountAfterTax="135.00"/>
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvCode="9143" RatePlanID="20540" Start="2022-12-20" End="2022-12-21"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <!-- ohne Komma - mit Dezimalstellen -->
                    <BaseByGuestAmt AmountAfterTax="3800" DecimalPlaces="2" NumberOfGuests="3" CurrencyCode="EUR"/>
                    <BaseByGuestAmt AmountAfterTax="3800" DecimalPlaces="2" NumberOfGuests="1" CurrencyCode="EUR"/>
                    <BaseByGuestAmt AmountAfterTax="4500" DecimalPlaces="2" CurrencyCode="EUR"/>
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-01-29" End="2023-01-31"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <!-- todo use DecimalPlaces 14995 -> 149.95 we save only the 149 -->
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="13698" DecimalPlaces="2" />
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="14698" DecimalPlaces="2" />
                </BaseByGuestAmts>
                <AdditionalGuestAmounts>
                    <AdditionalGuestAmount Amount="1000" DecimalPlaces="2" />
                </AdditionalGuestAmounts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-01-26" End="2023-01-28"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="139.95" />
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="149.95" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-10-10" End="2023-10-12"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="249.95" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
</RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>

OTA_HotelRateAmountNotifRS - Response versions

Usually a <Success/> is sent in response or appropriate error messages and/or warnings

Example OTA_HotelRateAmountNotifRS Response

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       EchoToken="b1e1a4a5cf11520d81fc9edbe781ba12" PrimaryLangID="de"
                       TimeStamp="2022-03-08T16:34:10+01:00" Target="Production" Version="2.01">
    <Success/>
</OTA_HotelRateAmountNotifRS>

Warnings

Each sent line with prices is considered and processed individually, therefore errors in the validation of parameters are only sent as a warning for this one line. (See also list of common error messages)

All other lines are processed independently.

The attributes used for checking are also output for each warning.

If there are warnings, the number of successfully processed rows is sent at the end as a separate notice. e.g.

1 of 3 incoming RateAmountMessage processed. See warnings before

Example OTA_HotelAvailNotifRS Response with warnings

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          EchoToken="fa9c12edfe5baba3b98deac1138ed5b2" PrimaryLangID="de"
                          TimeStamp="2022-03-08T15:48:27+01:00" Target="Production" Version="2.01">
    <Warnings>
        <Warning Code="448" Type="1">AmountAfterTax (155.99) ignored (NumberOfGuests 1 vs AdultsPerRoom 4)</Warning>
        <Warning Code="448" Type="1">AmountAfterTax (15.99) ignored (AgeQualifyingCode 8 is not 10)</Warning>
        <Warning Code="321" Type="1">RateAmountMessage cannot processed (amountAfterTax is null) - used attributes
            (AmountAfterTax: n/a, Start: 2022-12-26, End: 2022-12-27, InvTypeCode: 2625, RatePlanCode: TEST-BARS,
            RatePlanID: 0)
            </Warning>
        <Warning Code="404" Type="1">Invalid start date (2023-05-18) is in past</Warning>
    </Warnings>
</OTA_HotelAvailNotifRS>

Error messages

If serious errors occur, e.g. in the authentication or validation of the data, they are sent in an OTA_ErrorRS Response with @ErrorCode and @ErrorMessage

Example

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            EchoToken="283857aab0941e378f826b8eb96bbab1" PrimaryLangID="de"
                            TimeStamp="2023-06-08T14:39:03+02:00" Target="Production" Version="2.01">
    <Errors>
        <Error Code="448" Type="12">RateAmountMessages arttribute HotelCode (44) does not match request HotelCode (4)
        </Error>
    </Errors>
</OTA_HotelRateAmountNotifRS>

If all sent prices for the hotel cannot be processed, e.g. due to incorrect data, you will receive a special error message:

No valid RateAmountMessage found (0 of 11 incoming)

Then contact the service or connectivity team.

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            EchoToken="4ce1635ec9ac0944aacb17d0ea86a9ea" PrimaryLangID="de"
                            TimeStamp="2023-06-08T14:40:31+02:00" Target="Production" Version="2.01">

    <Errors>
        <Error Code="450" Type="10">Error during processing RateAmountMessages. No valid RateAmountMessage found (0 of
            11 incoming)
        </Error>
    </Errors>
</OTA_HotelRateAmountNotifRS>

List of error codes

Here is a list of common error messages when sending prices

ErrorCode ErrorMessage
101 RateAmountMessages not found (empty or not well formed XML payload)
111 Method not allowed for hotel - hotel must support RateAmountMessages for dynamic prices
210 HotelNotLinked - Hotel linked to another channel manager
211 HotelNotActivated - Hotel not found
104 InternalError - Empty HotelCode (HotelId) in accepted params (agentdutycode, hotelcode, ...)
220 RoomMappingError - Hotel does not have rooms created or configured
221 RoomMappingError - Hotel does not have rates created or configured
230 RoomMappingError - Invalid room code
231 RoomMappingError - Invalid room quantity
232 RoomMappingError - Invalid rate code (for Room/Rate combinations)
240 DateRangeError - Invalid date range
500 AmountAfterTax ignored (NumberOfGuests 1 vs AdultsPerRoom 2)
500 Error during processing RateAmountMessages. Maybe some attribute is null
500 too many lines (max. 4.000 lines) of RateAmountMessages

Example OTA_ErrorRS Response with error

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ErrorRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             EchoToken="968209e6b51ffeba7b2953801c4c8fce" PrimaryLangID="de" TimeStamp="2022-03-08T15:57:43+01:00"
             Target="Production" Version="1.000" 
             ErrorCode="211"
             ErrorMessage="HotelNotActivated - Hotel not found (HotelCode 1234 / AgentDutyCode 1)"/>

Example ** OTA_HotelRateAmountNotifRS** Response with error

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" 
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                       EchoToken="08b99bdc46a0ee67b620ecf88a1f30ac" PrimaryLangID="de" 
                       TimeStamp="2022-03-09T10:46:12+01:00" Target="Production" Version="2.01">
    <Errors>
        <Error Code="500" Type="1">StatusApplicationControl (InvCode="5306" Start="2022-10-01" End="2022-10-03") cannot
            processed. some attribute is null
        </Error>
    </Errors>
</OTA_HotelRateAmountNotifRS>