Retrieve Reservations
The connected PMS should retrieve reservations, modifications and cancellations from HotelRunner using the OTA_ReadRQ message. HotelRunner will respond with a OTA_ResRetrieveRS that contain the reservations, modifications or cancellations that meet the request criteria in the read request.
OTA_ReadRQ
The message below will return max: 10 undelivered reservations, modifications and cancellations for the hotel.
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2016-04-01T12:31:47+03:00" EchoToken="echo-1903">
<POS>
<Source>
<RequestorID Type="22" ID="PMS1"/>
</Source>
</POS>
<ReadRequests>
<HotelReadRequest>
<SelectionCriteria SelectionType="Undelivered"/>
</HotelReadRequest>
</ReadRequests>
</OTA_ReadRQ>
The message below will return max: 10 undelivered new/modified reservations for the hotel.
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2016-04-01T12:31:47+03:00" EchoToken="echo-1903">
<POS>
<Source>
<RequestorID Type="22" ID="PMS1"/>
</Source>
</POS>
<ReadRequests>
<HotelReadRequest>
<SelectionCriteria SelectionType="Undelivered" ResStatus="Book"/>
</HotelReadRequest>
</ReadRequests>
</OTA_ReadRQ>
The message below will return max: 10 undelivered cancellations for the hotel.
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2016-04-01T12:31:47+03:00" EchoToken="echo-1903">
<POS>
<Source>
<RequestorID Type="22" ID="PMS1"/>
</Source>
</POS>
<ReadRequests>
<HotelReadRequest>
<SelectionCriteria SelectionType="Undelivered" ResStatus="Cancel"/>
</HotelReadRequest>
</ReadRequests>
</OTA_ReadRQ>
OTA_ReadRQ Specification
| Element |
Number |
Description |
| OTA_ReadRQ |
1 |
Root element |
| @Version |
1 |
Current Version 1.0 |
| @EchoToken |
1 |
Globally unique identifier for the request, value will be returned as an EchoToken in the response. |
| @TimeStamp |
1 |
Time of the transaction in xml schema dateTime format |
| OTA_ReadRQ / POS / Source / RequestorID |
1 |
This identifies the system which is sending the reservation. This element must appear in the first Source element. |
| @Type |
1 |
Fixed at 22 (ESRP) |
| OTA_ReadRQ / ReadRequests |
1 |
|
| ReadRequests / HotelReadRequest |
1 |
|
| HotelReadRequest / SelectionCriteria |
1 |
|
| @SelectionType |
1 |
Must be "Undelivered" |
| @FromDate |
0 |
Reservations that are created after the FromDate |
| @FromLastUpdate |
0 |
Reservations that are updated after the FromLastUpdate |
| @ReservationNumber |
0 |
Searches for a specific reservation number |
| @ResStatus |
0..1 |
Allowed values are "Book", "Modify" or "Cancel". If omitted new, modified and cancelled reservations will be returned. |
OTA_ResRetrieveRS
This message is returned by HotelRunner in response to the OTA_ReadRQ. It's primary payload is a list of HotelReservations which meet the request criteria in the OTA_ReadRQ.
@MoreIndicator, if true, this indicates more items are available. If false, no more items are available.
Reservations that meet the request criteria are returned
HotelRunner is channeling reservations from multiple different booking sources. The OTA_ResRetrieveRS Specification below has a number listed next to the node name to indicate if the node is mandatory or not. The OTA_ResRetrieveRS spec below is not designed to appear exactly in the order presented below. Coding to HotelRunner should be flexible and allow for order variations to nodes/elements.
* The
element indicates a successful response
* In this example 2 new reservations are returned. As covered in Retrieve & Confirm Use Cases documents, the HotelRunner reservation identifiers are "R45221903" and "R45221409" and the message ids for these reservations are "1234567" and "78901234".
* The second UniqueID element with ID_Context="MESSAGE_UNIQUE_ID" is the unique id for this message. This identifier should be used to confirm the message once processed. @ID_CONTEXT Only present for the second UniqueID element and when present it will always be "MESSAGE_UNIQUE_ID"
<OTA_ResRetrieveRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2016-04-01T12:31:47+03:00" EchoToken="echo-1903" MoreIndicator=false>
<Success/>
<ReservationsList>
<HotelReservation CreateDateTime="2016-04-01T09:31:42+03:00" ResStatus="Book">
<UniqueID Type="14" ID="R45221903"/>
<UniqueID Type="16" ID="1234567" ID_Context="MESSAGE_UNIQUE_ID"/>
</HotelReservation>
<HotelReservation CreateDateTime="2007-12-09T08:51:45" ResStatus="Book">
<UniqueID Type="14" ID="R45221409"/>
<UniqueID Type="16" ID="78901234" ID_Context="MESSAGE_UNIQUE_ID"/>
</HotelReservation>
</ReservationsList>
</OTA_ResRetrieveRS>
No reservations are found that meet the request criteria
* The presence of the
element indicates successful processing but the lack of the ReservationsList element shows no reservations were available.
<OTA_ResRetrieveRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2016-04-01T12:31:47+03:00" EchoToken="echo-1903">
<Success/>
</OTA_ResRetrieveRS>
OTA_ResRetrieveRS Specification
The main payload of the OTA_ResRetrieveRS message is a list of HotelReservation elements. The content will vary because HotelRunner is delivering reservations from many different upstream sources (Booking Channels), many of which have vastly different reservation formats and data structures.
In general, the following can be said about HotelReservations:
A HotelReservation represents a single reservation made with an upstream system.
A HotelReservation can have one or more RoomStays, one for each room type booked.
A RoomStay represents a stay in one room type over a continuous timespan, non-continuous timespan stays (split stays) will result in multiple RoomStays.
A HotelReservation can have zero, one or many ResGuests linked to either the RoomStay the guest stay in or the reservation.
Elements and attributes marked with Number=1 or more are mandatory and will always be sent. 0..n means that the element or attribute is optional.
| Element |
Number |
Description |
| OTA_ReadRS |
1 |
Root element |
| @Version |
1 |
Current Version 1.0 |
| @EchoToken |
1 |
Return the EchoToken from the request message. |
| @TimeStamp |
1 |
Time of the transaction in xml schema dateTime format |
| OTA_ResRetrieveRS / Success |
0..1 |
Should only be present if the request processed successfully. The Errors node will not be present if the Success node is present. |
| OTA_ResRetrieveRS / Errors |
0..1 |
Contains a list of errors if the request failed to process. |
| Errors / Error |
1..n |
Should be at least one node if there is an Errors Node. |
| @Type |
1 |
Mandatory if Error present. Any type from the OTA code table for 'Error Warning Type (EWT)' can be used. |
| @Code |
0..1 |
Any code from the OTA code table for 'Error Codes (ERR)' can be used. |
| OTA_ResRetrieveRS / ReservationsList |
0..1 |
ReservationList is only present if there are HotelReservation elements. |
| ReservationsList / HotelReservation |
1..n |
At least one reservation element if ReservationList exists. See HotelReservationType |
HotelReservationType
| Element |
Number |
Description |
| Source / RequestorID |
0..1 |
This identifies the system which is sending the reservation. This element will only appear in the first Source element. |
| Source / BookingChannel |
1 |
Contains booking channel information |
| Reservation / ResGuests / ResGuest |
0..n |
One instance of ResGuest per reservation guests. This guest information is dependent on the sometimes limited information retrieved from the booking agents. ResGuests might not always be directly linkable to the RoomStays. Either all ResGuests are linked to RoomStays or none are. See ResGuestType |
| POS / Source |
1..2 |
Source of the reservation. A second POS / Source node can be present to define a secondary channel source. |
| HotelReservation / UniqueID |
1..2 |
The reservation reference in HotelRunner. The first UniqueID element will contain the unique identifier for the entire reservation. This identifier will identify the reservation through any subsequent modifications or cancellations. The second UniqueID element with ID_Context="MESSAGE_UNIQUE_ID" is the unique id for this message. This identifier should be used to confirm the message once processed |
| HotelReservation / Services / Service |
0..n |
A list of service fees and extra charges linked to the HotelReservation. See ServiceType |
| HotelReservation / RoomStays / RoomStay |
0..n |
One instance of RoomStay per room booked. A RoomStay element will always exist if ResStatus is "Book" or "Modify". If ResStatus is "Cancel" it is possible that no RoomStay element exists. See RoomStayType |
| HotelReservation / ResGlobalInfo |
1 |
Contains general information about the Reservation. See ResGlobalInfo |
| HotelReservation / POS |
1 |
Point of sale |
| BookingChannel / CompanyName |
1 |
Name of the Booking Channel. |
| @Type |
1 |
Value '14' is the unique id for the reservation in HotelRunner. Value '16' is the unique id for the message transferring the reservation. |
| @Type |
1 |
Fixed at 22 (ESRP) |
| @ResStatus |
1 |
Status is "Book", "Modify" or "Cancel" |
| @Primary |
1 |
Indicates the primary booking source. |
| @LastModifyDateTime |
0..1 |
This indicates the last date and time when the reservation was last modified. Mandatory if ResStatus is "Modify" or "Cancel". |
| @ID_Context |
1 |
Only present for the second UniqueID element and when present it will always be "MESSAGE_UNIQUE_ID" |
| @ID |
1 |
Identifier of the reservation according to HotelRunner. Note, this is NOT the reservation id according to the upstream system. This is located in the HotelReservationID element. |
| @ID |
1 |
Value is always 'HotelRunner' |
| @CreateDateTime |
1 |
This is the date when the reservation was first made. Mandatory if ResStatus is "Book". |
| @Code |
0..1 |
HotelRunner's code to identify the Booking Channel. See the OTA Booking Channel Type (BCT) table for reference. For secondary channels this code may not be available, when present it will be the secondary channel code as provided by the source channel. |
ResGlobalInfo
| Element |
Number |
Description |
| HotelReservationIDs / HotelReservationID |
0..2 |
Reference number/string or PNR as supplied by the Booking agent will be supplied here. |
| @ResID_Type |
1 |
Will be sent as 14. |
| @ResID_Value |
1 |
Reference number/string supplied by the Booking agent |
| Total |
0..1 |
The total amount for the Reservation. Will add up to the sum of the RoomStay totals PLUS any additional fees sent by the BookingAgent. NOTE: It is possible that some OTAs do not provide any form of Rate information. As such we cannot guarantee Rate information will be provided. Currently Hotelbeds (HBD) is a known channel that does not always provide Rate information. See TotalType |
| Profiles |
0..1 |
This is a listing of Profiles associated with the reservation that are not Guests. This includes Customers, Travel Agents and Travel Arrangers. The Customer is the contact person for the Reservation. If the customer is also a guest, they will also be included in the ResGuests |
| Fees / Fee |
0..n |
A container for added fees |
| @TaxInclusive |
1 |
If 'true' the commission amount provided is tax inclusive, if 'false' the commission amount is not tax inclusive |
| @Type |
1 |
Always 'Inclusive' as HotelRunner reports gross Totals. Totals are inclusive of fees |
| Fee / Taxes |
0..1 |
See TaxesType |
| Fee / Description / Name |
0..1 |
Identifies the type of fee. |
| Fee / Description / Text |
0..1 |
A description of the fee |
| DepositPayments |
0..1 |
Contains the deposit information |
| DepositPayments / GuaranteePayment / AmountPercent |
1 |
|
| @Amount |
0..1 |
The deposit as a currency amount. At least @Amount or @Percent will be populated. |
| @CurrencyCode |
0..1 |
This is the ISO currency code of the deposit. Mandatory if @Amount exists. |
| @Percent |
0..1 |
This is the percentage of the Total charge for the deposit (rounded to 3 decimal places). If the the Total.amountAfterTax is provided, it will be a percentage of this value. If only the amountBeforeTax is provided it will be the percentage of this value. At least @Amount or @Percent will be populated. |
| @TaxInclusive |
0..1 |
Indicates if tax is included in @Amount |
| DepositPayments / GuaranteePayment / Description / Text |
0..1 |
A text description of the deposit |
| Guarantee |
0..1 |
Guarantee information. See Guarantee Type |
| Comments / Comment / Text |
0..n |
Reservation comments |
ResGuestType
| Element |
Number |
Description |
| @ResGuestRPH |
0..1 |
This value links the ResGuest to RoomStay(s) where possible. You can find the links in RoomStay / ResGuestRPHs |
| @ArrivalTime |
0..1 |
The arrival time of the guest in the form HH:mm:ss. |
| ResGuest / Profiles |
1 |
Contains the guest profile information |
| ResGuest / Comments / Comment |
0..1 |
Container for extra information about the guest |
| @Name |
0..1 |
Identifier for the comment, current supported names are |
| Comment / Text |
1 |
Text for the guest extra information |
RoomStayType
| Element |
Number |
Description |
| RoomStay / RoomTypes / RoomType |
0..1 |
Container for room information, will be omitted if none was provided by the source channel. There will only ever be one RoomType per RoomStay |
| @RoomType |
0..1 |
The name of the RoomType as provided by source channel |
| @RoomTypeCode |
0..1 |
Room code, identifier for the room |
| RoomType / RoomDescription / Text |
0..1 |
A text description of the room |
| RoomType / AdditionalDetails |
0..n |
Container for additional information about this room provided by the source channel. See AdditionalDetailsType |
| RoomStay / RatePlans |
0..1 |
Container for room information, will be omitted if none was provided by the source channel |
| RatePlans / RatePlan |
0..n |
Contains information for the Rate Plan(s) used for the RoomStay. |
| @RatePlanCode |
0..1 |
Rate code, identifier for the rate plan |
| @RatePlanName |
0..1 |
Name of the rate plan as provided the source channel |
| @EffectiveDate |
1 |
The effective date of the RatePlan |
| @ExpireDate |
1 |
The expire date for a RatePlan, this should be considered an exclusive date, the date for which the current rate plan information is no longer valid. |
| RatePlan / RateDescription / Text |
0..1 |
A text description of the rate |
| RatePlan / AdditionalDetails |
0..n |
Container for additional information for the room provided by the source channel. See AdditionalDetailsType |
| RoomStay / RoomRates / RoomRate |
1..n |
Multiple RoomRates per RoomStay. Multiple rates are listed under each RoomRate. This can happen when there is a single room booked but more than one rate plan applies during the stay. See RoomRateType |
| RoomStay / GuestCounts / GuestCount |
0..3 |
How many guests will be staying in the room. The count is split over potentially three GuestCount elements under GuestCounts, one for each type of guest: adult, child or infant. |
| @AgeQualifyingCode |
1 |
Specifies the guest type for this GuestCount - uses OTA Spec for identifiers, will be one of three values 10 - Adult 8 - Child 7 - Infant |
| @Count |
1 |
The actual count for this type of guest |
| RoomStay / TimeSpan |
1 |
Contains the timespan which this RoomStay covers |
| @Start |
1 |
Check in date |
| @End |
1 |
Check out date |
| RoomStay / Total |
0..1 |
The total amount of the stay. Will add up to the sum of Rate/Base*NumberOfUnits. IE The total cost for the RoomStay. NOTE: It is possible that some OTAs do not provide any form of Rate information and as such a RoomStay / Total cannot be provided in such cases. Currently Hotelbeds (HBD) is a known channel that does not always provide Rate information. |
| RoomStay / ServiceRPHs / ServiceRPH |
0..n |
Contains links to any service or extra charges for the room |
| @RPH |
1 |
Links a Service/@ServiceRPHA to this RoomStay |
| RoomStay / ResGuestRPHs / ResGuestRPH |
0..n |
Used to link guests from the ResGuests list to the RoomStay |
| @RPH |
1 |
Links a ResGuest/@ResGuestRPH to this RoomStay |
| RoomStay / Comments / Comment / Text |
0..1 |
RoomStay comments |
RoomRateType
| Element |
Number |
Description |
| RoomStay / RoomRates / RoomRate |
1..n |
Multiple RoomRates per RoomStay. Multiple rates are listed under each RoomRate. This can happen when there is a single room booked but more than one rate plan applies during the stay. |
| @RoomTypeCode |
1 |
The code of the room booked |
| @NumberOfUnits |
1 |
Always 1. Each room will be listed in it's own RoomStay element. |
| @RatePlanCode |
1 |
This is the rate booked for the room type code listed in the RoomTypeCode attribute. |
| RoomRate / Rates |
0..1 |
Container for the daily rate breakdown information, if none was provided by the channel this will be omitted |
| Rates / Rate |
1..n |
The Rate element contains a timespan with daily rate information. The dates covered in the Rates will cover all the dates in the RoomStay/TimeSpan element. |
| @RateTimeUnit |
1 |
Always "Day" |
| @EffectiveDate |
1 |
The starting date of the rate in the form yyyy-MM-dd. This date is inclusive. |
| @ExpireDate |
1 |
ExpireDate is the first day after the applicable period (e.g. when expire date is 2012-04-03 the last date of the period is 2012-04-02). Format yyyy-MM-dd. This date is exclusive. |
| @UnitMultiplier |
1 |
Will be equal to the number of days between EffectiveDate and ExpireDate. Multiply with the UnitMultiplier to get the total cost for the date span. |
| Rate / Base |
0..1 |
Specifies the base per-day rate for the room. This is the gross amount charged for the room, not including any discounts or extra charges. |
| Rate / Total |
0..1 |
The total amount charged for the Rate. Will be equal to the Base amount with the extras and discounts applied. Note that the Total is gross, in other words the FULL amount charged for the per date rate as provided by the source channel. |
| RoomRate / ServiceRPHs / ServiceRPH |
0..n |
Contains links to any service or extra charges for the rate |
| @RPH |
1..n |
Links a Service/@ServiceRPHA to this RoomRate |
AdditionalDetails
| Element |
Number |
Description |
| AdditionalDetails / AdditionalDetail |
0..n |
Container for additional information provided by the source channel for the rate |
| AdditionalDetail / DetailDescription / Text |
1..n |
The actual details provided by the channel |
| AdditionalDetail / DetailDescription |
0..1 |
|
| @Type |
1 |
Describes the additional information, please refer to the OTA Additional Detail Type (ADT) Code Table. 43: Meal plan information 15: Promotion information |
| @Code |
0..1 |
A reference code provided by the source channel for the additional details. For example promotional codes |
ProfilesType
| Element |
Number |
Description |
| Profiles / ProfileInfo |
1..n |
Profile information |
| ProfileInfo / Profile |
1 |
Contains the profile information |
| @ProfileType |
1 |
The type of profile 1: Customer |
| Profile / Customer |
|
|
| Customer / PersonName / NamePrefix |
0..1 |
Name prefix |
| Customer / PersonName / GivenName |
1 |
The name of the profile |
| Customer / PersonName / MiddleName |
0..1 |
The middle name of the profile |
| Customer / PersonName / Surname |
1 |
The last name of the profile |
| Customer / Telephone |
0..1 |
Contact telephone number for the profile if available |
| @PhoneNumber |
0..1 |
The actual number, will be there if the Telephone element is there |
| Customer / Email |
0..1 |
The email address of the profile if available |
| Customer / Address |
0..n |
Address information for the profile if available |
| Address / AddressLine |
0..n |
One or more address lines for the profile |
| Address / CityName |
0..1 |
Customer city of residence if available |
| Address / PostalCode |
0..1 |
Post code for profile if available |
| Address / StateProv |
0..1 |
State or province name |
| Address / CountryName |
0..1 |
Country name |
| Address / CompanyName |
0..1 |
Company name |
ServiceType
The Service structure is used for passing on information about charges for extras and services. Services can be provided at the HotelReservation level (no ServiceRPH) or to a RoomStay or RoomRate. The ServiceRPH serves only to link a charge to a room or a rate.
All Service totals provided should be considered full amounts added to the base reservation charge. In other words, the charges are not per person or per day but full charges. The total amounts provided for the RoomStay and Reservation should be considered as inclusive of extras.
| Element |
Number |
Description |
| @ServiceInventoryCode |
1 |
The identifier code for the service as given by the source booking channel will be provided here. In the absence of a specific code being provided by the channel, the type of charge will be specified via one of the types specified in the Service and Extra Charge Reference Table. |
| @ServiceRPH |
0..1 |
This links a Service to a RoomStay or a RoomRate. The absence of a ServiceRPH indicates that this is a HotelReservation level charge |
| @Inclusive |
1 |
Always 'true', HotelRunner reports totals as inclusive of charges and extras |
| @Quantity |
1 |
The number of units included in the charge. This value does not affect the Total amount |
| @ID |
0..1 |
The reference id provided for a extra/service by the source booking channel |
| @ID_Context |
0..1 |
If ID present, will always be 'CHANNEL' |
| @Type |
1 |
A reference to the type of object defined by the UniqueID element. Always "18" to indicate other in the OTA Unique Id Type (UIT) table |
| Service / Price |
1 |
Container for the price |
| Price / Base |
0..1 |
The amount per unit for this extra charge as provided by the hotel.See BaseType (for details) |
| Price / Total |
1 |
See TotalType |
| Price / RateDescription / Text |
0..1 |
A text description of the service/extra |
| Service / ServiceDetails |
0..1 |
|
| ServiceDetails / TimeSpan |
0..1 |
Start date for which the extra charge applies |
| @Start |
0..1 |
Start date for which the extra charge applies |
| @End |
0..1 |
End date for which the extra charge applies. This is an inclusive date, the last date for which the charge applies |
BaseType
| Element |
Number |
Description |
| @CurrencyCode |
0..1 |
The ISO currency code for the unit amount |
| @AmountAfterTax |
0..1 |
The unit amount after tax |
| @AmountBeforeTax |
0..1 |
The unit amount before tax |
| Taxes |
0..1 |
The unit tax amount for the BaseType See TaxesType |
| @Amount |
0..1 |
The unit tax amount |
TotalType
| Element |
Number |
Description |
| @CurrencyCode |
0..1 |
The ISO currency code for the unit amount |
| @AmountAfterTax |
0..1 |
The total amount after tax |
| @AmountBeforeTax |
0..1 |
The total amount before tax |
| Taxes |
0..1 |
The total tax amount for the BaseType See TaxesType |
| @Amount |
0..1 |
The total tax amount |
TaxesType
| Element |
Number |
Description |
| Taxes / Tax |
0..n |
Zero to many tax breakdowns |
| @Code |
1 |
The type of tax being applied to the total. Refer to the code table OTA Fee Tax Type (FTT) |
| @Percentage |
0..1 |
Tax percentage |
| @Amount |
0..1 |
Tax amount |
| Tax / TaxDescription / Text |
0..1 |
Text description of the tax |