Migrating from the Booking Retrieval and Confirmation APIsCopy link

If you have implemented the Booking Retrieval and Booking Confirmation APIs, we encourage you to migrate over to the reservation management capability. The following sections outline how reservations are managed using the GraphQL API in comparison to the booking APIs.

Reservation retrieval

The core functionality of both BRBC and reservation management resides in the reservation details, though there are key differences between them. To show the similarities and differences between BRBC and reservation retrieval, the full requests are broken into sections below to provide context of their functionality.

General reservation information

The main details of a reservation, such as guest name and contact details, are provided in both calls and are similar in output. Note that special requests are captured several objects in reservation retrieval, such as the valueAddedPromotions and loyaltyTier objects. Refer to the reservations query for details about how reservations data is reported.

1<PrimaryGuest> 
2  <Name givenName="John" middleName="F." surname="Smith"/> 
3  <Phone countryCode="1" cityAreaCode="514" number="5558975" extension="3233"/> 
4</PrimaryGuest> 
5<RewardProgram code="QI" number="2456"/> 
6<SpecialRequest code="5">Bill only nights booked by Expedia to cc# @ ck-in gst pays incid </SpecialRequest> 
7<SpecialRequest code="1.23">2 Queen</SpecialRequest> 
8<SpecialRequest code="2.1">Non-smoking</SpecialRequest> 
9<StayDate arrival="2020-12-27" departure="2020-12-30"/>     

Filters when retrieving reservations

Request for reservation by both BRBC and reservation management can be filtered to retrieve specific reservation details. Below are some examples for BRBC and reservation management.

To filter by reservation ID:

1<BookingRetrievalRQ xmlns="http://www.expediaconnect.com/EQC/BR/2014/01"> 
2  <Authentication username="testuser" password="testpass"/> 
3  <Hotel id="3546"/> 
4  <ParamSet> 
5    <Booking id="849123"/> 
6  </ParamSet> 
7</BookingRetrievalRQ> 

To filter by checkout date:

1<BookingRetrievalRQ xmlns="http://www.expediaconnect.com/EQC/BR/2014/01"> 
2  <Authentication username="testuser" password="testpass"/> 
3  <ParamSet> 
4    <NbDaysInPast>30</NbDaysInPast> 
5  </ParamSet> 
6</BookingRetrievalRQ>

The following example is specific to the Booking Retrieval API where all pending bookings will be retrieved. Reservation management does not use this approach; all new reservations are sent through a notification.

<BookingRetrievalRQ xmlns="http://www.expediaconnect.com/EQC/BR/2014/01"> 
  <Authentication username="testuser" password="testpass"/> 
</BookingRetrievalRQ> 

Room types and rate plans

For the room type and rate plan details, the same general details are shown below and indicate the room level ID and the rate plan ID to which the reservation belongs.

1<Hotel id="3546"/>      
2<RoomStay roomTypeID="965645" ratePlanID="956589"> 

Room rates and reservation amounts

When reservations are made, one of the most important aspects of each reservation is dates and amounts. These details are managed comparably by BRBC and reservation retrieval, but there are some key differences.

Reservation management has a more comprehensive breakdown of the amounts, including tax, compensation, per night details, accelerator, and promotional amounts per night.

Booking Retrieval element details are in the <PerDayRates>, which is provided once per day of the stay and indicates the rate for each day. The currency attribute is the three-letter currency code assigned to the property in Partner Central, based on the ISO-4217 specification. Data type: string. Child elements:

• <PerDayRate> - Details of the per day rate. 1 to 28 occurrences of this container element. Includes the following attributes:
  • stayDate - Date to which the room rate applies. Data type: date, as defined in ISO 8601 format. Will always be in the following format: YYYY-MM-DD.
  • baseRate - Base rate for one day of the stay, including any promotional discounts. Expedia Group returns the net rate for Expedia Collect bookings even when the property is managing the lowest available rate (LAR). Expedia Group will return the sell rate for Updated Expedia Collect bookings and Hotel Collect bookings, even when the property is managing net rate. Data type: decimal, minimum value = 0
  • extraPersonFees - Extra person fees included in the total amount, if any. Data type: decimal, minimum value = 0
  • hotelServiceFees - Hotel service fees/charges included in the total amount, if any. Data type: decimal, minimum value = 0
  • promoName - Name of promotion applied to base rate. Promotions and their notification codes can be configured in Partner Central or set up by the Expedia Group Market Manager for the property. If the property uses Expedia Flexible Rate, the string will begin with “EFR*” if an Expedia Flexible Rate is applied to this stay date. Data type: string, string length will not exceed 32 characters.
• <Total> - Container element for the total price of the booking. Includes the following attributes:
  • amountAfterTaxes - Total charge, which could either be a net or sell value. Specifics on what is included in the amount can be found here. Data type: decimal, minimum value = 0
  • amountOfTaxes - Amount of taxes included in the amountAfterTaxes attribute. Data type: decimal, minimum value = 0
  • amountOfTaxes - Total taxes, which could either be a net or gross value. Specifications on what is included in the amount can be found here. This will be the sum of all amounts in the child elements. With the current implementation Expedia only sends one child element for, but this could change in the future. Data type: decimal, minimum value = 0
  • currency - The currency attribute is the 3-letter currency code assigned to the property in Partner Central, based on the ISO-4217 specification. Data type: string

1<PerDayRates currency="USD"> 
2  <PerDayRate stayDate="2025-01-10" baseRate="300.00" promoName=” Winter Sale” /> 
3  <PerDayRate stayDate="2025-01-11" baseRate="300.00" promoName=” Winter Sale” /> 
4  <PerDayRate stayDate="2025-01-12" baseRate="300.00" promoName=” Winter Sale” /> 
5  <PerDayRate stayDate="2025-01-13" baseRate="300.00" promoName=” Winter Sale” /> 
6  <PerDayRate stayDate="2025-01-14" baseRate="300.00" promoName=” Winter Sale” /> 
7</PerDayRates> 
8<Total amountAfterTaxes="1355.70" amountOfTaxes="178.20" currency="USD"/> 

Guest counts

BRBC and reservation management provide the details of guest count similarly. The main difference is that Booking Retrieval API breaks the ages into child elements of the GuestCount element. Reservation management provides the ages as an array in its own field.

1<GuestCount adult="2" child="3"> 
2  <Child age="3"/> 
3  <Child age="6"/> 
4  <Child age="17"/> 
5</GuestCount> 

Payment details

Payment details are managed very differently by BRBC and reservation management:

• Reservation management requires an additional layer of security. A Payments API query must be made to acquire payment details using a payment token, which is retrieved in the reservations query.
• Booking Retrieval API includes the payment details in the payload of the call.

One distinct advantage that reservation management has over the Booking Notification API is the payment details can be collected at any time. This is very useful. For example, a front desk clerk may need to override the Expedia Virtual Card with the guest’s credit card for payment during the check-in process. This can easily be addressed by adding a call to allow the Expedia Virtual Card to collect payment and prevent a double-charge to the guest.

1<PaymentCard cardCode="VI" cardNumber="****23456" expireDate="1206" seriesCode="981"> 
2  <CardHolder name="ExpediaVirtualCard" address="1111 Expedia Group Way W" city="Seattle" stateProv="WA" country="US" postalCode="98119"/> 
3</PaymentCard> 

Reservation delivery and confirmation

With BRBC, booking details need to be retrieved with a GET call followed by an acknowledgement response. Your system is constantly sending messages to our system asking for new reservations that have been created. If a reservation needs to be adjusted, the system will indicate that a change has occurred. Booking Retrieval is dependent on your system making a call for the modified reservation. The attribute type="Modify" or type="Cancel" in the <Booking> element is used to get details for reservations that have been modified. In contrast, reservation management sends a notification when reservations are created and then you can use the reservations query to retrieve reservation details. Confirmations for both are required to ensure the reservation is not sent to the alternative delivery method.

Reservation notifications

Below is an example of a modified reservation. For the Booking Retrieval API, the key difference is the “type,” which indicates the type of booking. For reservation management, a payload is sent with the event type “MODIFIED” indicating the change. The same behavior is true for cancelled bookings, though the Booking Retrieval type will be “cancel” and the reservation management event type will be “CANCELLED.”

1<BookingRetrievalRS xmlns="http://www.expediaconnect.com/EQC/BR/2014/01"> 
2  <Bookings> 
3    <Booking id="3465456" type="Modify" createDateTime="2006-10-25T09:30:47Z" source="Expedia" status="pending" confirmNumber="EXP4433"> 
4      <Hotel id="3546"/> 
5      <RoomStay roomTypeID="965645" ratePlanID="956589"> 
6        <StayDate arrival="2007-02-24" departure="2007-02-28"/> 
7        <GuestCount adult="2"/> 
8        <PerDayRates currency="EUR"> 
9          <PerDayRate stayDate="2007-02-24" baseRate="115.00"/> 
10          <PerDayRate stayDate="2007-02-25" baseRate="115.00"/> 
11          <PerDayRate stayDate="2007-02-26" baseRate="115.00"/> 
12          <PerDayRate stayDate="2007-02-27" baseRate="115.00"/> 
13        </PerDayRates> 
14        <Total amountAfterTaxes="500.00" amountOfTaxes="40.00" currency="EUR"/> 
15      </RoomStay> 
16      <PrimaryGuest> 
17        <Name givenName="Jerry" middleName="W." surname="Lay"/> 
18        <Phone countryCode="1" cityAreaCode="514" number="5558512"/> 
19      </PrimaryGuest> 
20      <RewardProgram code="QI" number="2456"/> 
21      <SpecialRequest code="1.14">1 King</SpecialRequest> 
22    </Booking> 
23  </Bookings> 
24</BookingRetrievalRS> 

Reservation confirmation

After reservation details are collected, a response with confirmation of the reservation (including the hotel confirmation code) is expected to complete the booking cycle.

1<BookingConfirmRQ xmlns="http://www.expediaconnect.com/EQC/BC/2007/09"> 
2  <Authentication username="testuser" password="testpass"/> 
3  <Hotel id="3546"/> 
4  <BookingConfirmNumbers> 
5    <BookingConfirmNumber bookingID="848483849123" bookingType="Book" confirmNumber="8675309" confirmTime="2008-04-25T09:30:47Z"/> 
6  </BookingConfirmNumbers> 
7</BookingConfirmRQ>   

Record count

When retrieving reservations, BRBC can retrieve up to 125 records at a given time for a property. This limitation causes issues when validating reservations. In contrast, reservation management can retrieve up to 10,000 records per request, which are paginated up to 25 records per page. And you can query up to 465 days in the past (based on the checkout date) and up to 500 days in the future (based on checkout date.)

Reservation update

Reservations are often modified, for example, to simply add special requests or to cancel an entire reservation. These are the types of modifications:

• Soft modification: A change that does not impact the financials, such as a special request or name change.
• Hard modification: A change that impacts the financials, such as dates added or changed or a room or rate change.
• Cancellation: The reservation is cancelled in the system and no longer active.

When a reservation is changed, we send the booking ID to the partner system with a message type that indicates a change type="Modify" for Booking Retrieval or “MODIFIED” for reservation management. The number sent is the original booking ID made at the time of the reservation. However, in EPC, the original reservation is shown as “cancelled”, and a new reservation is created with a new booking ID. This is because we cancel the reservation and create a new reservation, which impacts inventory, room type, and possibly rates (depending on how the reservation was modified). But for you, to reduce confusion, we send the original booking ID with the modified details to indicate the changes.

Modified reservations contain the most recent information about a reservation (new information, modified information, or information that was on the original reservation). A modified reservation looks like a new reservation because it contains the same types of reservation information, except the "booking type" attribute of the <Booking> element is changed from "Book" to "Modify."

Example of a booking element for a modified booking: <Booking id="44654" type="Modify" createDateTime="2006-10-27T11:33:19Z" source="Expedia"></Booking>

Reservation management limitations:

• Modifications and cancellations made after a traveler’s arrival will not trigger notifications (event types MODIFIED/CANCELLED).
• In-flight reservations that were delivered through Booking Retrieval but not confirmed through the API will not trigger future event notifications for the following scenarios:
  • If a software connection is switched to a system that has implemented the reservation management capability
  • If the default booking API is switched to reservation management in the same system
• If a reservation is created and a webhooks notification is sent, the reservation cannot be retrieved or confirmed using any of the booking APIs. The reservation can be only delivered end-to-end through one API (reservation management or one of the booking APIs).

Error handling

For error handling, reservation management and BRBC manage error codes differently. Many of the GraphQL errors are provided in messages in the response, and error details are included in a message field. Even though an HTTP response of 200 is reported, there may be an error with the call. However, the error included in the message provides details and the line number where the error exists, which makes troubleshooting easier.

Reservation management and BRBC share the same standard HTTP status codes. And for both BRBC and reservation management, if the booking fails, an email notification is sent. Request messages that receive these errors will not be retried.

• Booking Retrieval and Booking Confirmation: error codes There are two sets of error codes, one for the Booking Retrieval, and one for Booking Confirmation.

• Reservation management error classes If an error occurs during the execute phase of the GraphQL lifecycle, it is associated with the GraphQL execution, and an error object is returned to the requester. An HTTP or GraphQL request error results in a non-200 status code, while a GraphQL execution error results in a 200 status code. For complete information about reservation management error codes, click here.