Availability and rates APIs
Booking APIs
Property mgmt APIs
Developer Tools
Reservation management
Getting startedReservation management

Migrating from Booking Notification API

If you have implemented the Booking Notification API, 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 Notification API.

Reservation retrieval

The core functionality of both the Booking Notification API and reservation management resides with the reservation details, though there are key differences between them:

  • Reservation retrieval (reservations query) can be called at any time (any number of requests) to get reservation information.
  • Booking Notification API sends details when the booking is created (one call). After that, details are no longer sent.

To show the similarities and differences between the Booking Notification API and the reservation retrieval capability, the full calls will be 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<RoomStays> 
2  <RoomStay> 
3    <BasicPropertyInfo HotelCode="1154286"/>    
4    <ResGuestRPHs>    
5      <ResGuestRPH RPH="1"/>    
6    </ResGuestRPHs>    
7    <SpecialRequests>    
8      <SpecialRequest Language="en-us" RequestCode="1.14">    
9        <Text Formatted="false" Language="en-us">1 king bed</Text>    
10      </SpecialRequest>    
11      <SpecialRequest Language="en-us" RequestCode="2.1">    
12        <Text Formatted="false" Language="en-us">Non-Smoking</Text>    
13      </SpecialRequest>    
14      <SpecialRequest Language="en-us" RequestCode="5">    
15        <Text Formatted="true" Language="en-us">Hotel Collect Booking Collect Payment From Guest</Text>    
16      </SpecialRequest>    
17    </SpecialRequests>    
18  </RoomStay>    
19</RoomStays>    
20<ResGuests>    
21  <ResGuest AgeQualifyingCode="10" ResGuestRPH="1">    
22    <Profiles>    
23      <ProfileInfo>    
24        <Profile ProfileType="1">    
25          <Customer>    
26            <PersonName>    
27              <GivenName>Etienne</GivenName>    
28              <Surname>Tester</Surname>    
29            </PersonName>    
30            <Telephone AreaCityCode="321" CountryAccessCode="1" PhoneNumber="3331111"/>    
31            <Email>customer@email.com</Email>    
32          </Customer>    
33        </Profile>    
34      </ProfileInfo>    
35    </Profiles>    
36  </ResGuest>    
37</ResGuests>    
38<ResGlobalInfo>    
39  <HotelReservationIDs>    
40    <HotelReservationID ResID_Dte="2016-05-17T11:25:00-07:00" ResID_Source="Expedia" ResID_Type="8" ResID_Value="13357309"/>    
41  </HotelReservationIDs>    
42</ResGlobalInfo>

Room types and rate plans

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

Note: For Hotel Collect properties, the A- prefix is no longer added to the source value and the A suffix is no longer appended to the rate ID as was done by the booking APIs.

Room type examples:

  • Booking Notification:

    <RoomType IsRoom="true" RoomTypeCode="50287"/> </RoomTypes>

  • Reservation retrieval:

    "unitIds": {"id": "50287", "idSource": "EXPEDIA"}

Rate plan ID examples:

  • Booking Notification:

    <RatePlan EffectiveDate="2016-05-29" ExpireDate="2016-05-30" RatePlanCode="113702A"> 
      <CommissionPercent="0.2000"/>
    </RatePlan>

    The compensation amount is provided by <EffectiveDate> for the stay date and <ComissionPercentage> amounts for the day.

  • Reservation retrieval: 

    "rateIds": [{"id": "290105074","idSource": "EXPEDIA"},{"id": "290105074","idSource": "SUPPLIER"}]

    Compensation amounts are displayed under the amounts: 

    {"summary": ["date": "2023-11-06", "type": "COMMISSION_TOTAL", "percent": 0.15]}
1<RoomTypes>   
2  <RoomType IsRoom="true" RoomTypeCode="50287"/>   
3</RoomTypes>   
4<RatePlans>   
5  <RatePlan EffectiveDate="2016-05-29" ExpireDate="2016-05-30" RatePlanCode="113702A">   
6    <CommissionPercent="0.2000"/>   
7  </RatePlan>   
8  <RatePlan EffectiveDate="2016-05-30" ExpireDate="2016-05-31" RatePlanCode="113702A">   
9    <Commission Percent="0.2000"/>   
10  </RatePlan>   
11  <RatePlan EffectiveDate="2016-05-31" ExpireDate="2016-06-01" RatePlanCode="113702A">   
12    <Commission Percent="0.2000"/>   
13  </RatePlan>   
14  <RatePlan EffectiveDate="2016-06-01" ExpireDate="2016-06-02" RatePlanCode="113702A">   
15    <Commission Percent="0.2000"/>   
16  </RatePlan>   
17  <RatePlan EffectiveDate="2016-06-02" ExpireDate="2016-06-03" RatePlanCode="113702A">   
18    <Commission Percent="0.2000"/>   
19  </RatePlan>   
20</RatePlans>

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 Booking Notification and reservation retrieval, but there are some key differences.

Booking Notification:

  • Accelerators for Booking Notification are displayed in the <RatePlans> element.
  • For the daily amounts, Booking Notification starts with the <RoomRateEffectiveDate> for each day and then displays the daily amount information.
  • Booking Notification will indicate if the reservation has a promotion. However, it will not provide the percentage or the derived amount from the base rate.

Reservation retrieval:

  • Accelerators are a unique object in the amounts object.
  • Reservation retrieval provides "nightlyPayments": {"dailyAmounts": [...]} and then provides the date and type of amount.
  • Reservation retrieval provides a promotion object that retrieves percentages and amounts derived from the base rate: 
    1"type": "DISCOUNT",  
    2"description": "Member-only deal (ongoing)",  
    3"amount": {  
    4  "currencyCode": "EUR",  
    5  "amount": "-33.75"  
    6},  
    7"percent": null

Reservation retrieval mirrors Expedia Partner Central fields and the structure of payment amounts.

1<RoomRates>
2  <RoomRate EffectiveDate="2025-01-10" ExpireDate="2025-01-11" NumberOfUnits="1" PromotionCode="EFR Winter Sale" RatePlanCode="202323288" RoomTypeCode="202323288">  
3    <Rates> 
4      <Rate EffectiveDate="2025-01-10" ExpireDate="2025-01-11" RateTimeUnit="Day" UnitMultiplier="1"> 
5        <Base AmountBeforeTax="300.00" CurrencyCode="USD"/> 
6        <Fees> 
7          <Fee Amount="0.00" Code="1" CurrencyCode="USD" TaxInclusive="false" Type="Exclusive"/> 
8        </Fees> 
9      </Rate> 
10    </Rates> 
11  </RoomRate>    <RoomRate EffectiveDate="2025-01-11" ExpireDate="2025-01-12" NumberOfUnits="1" PromotionCode="EFR Winter Sale" RatePlanCode="202323288" RoomTypeCode="202323288">  
12    <Rates> 
13      <Rate EffectiveDate="2025-01-11" ExpireDate="2025-01-13" RateTimeUnit="Day" UnitMultiplier="1"> 
14        <Base AmountBeforeTax="300.00" CurrencyCode="USD"/> 
15        <Fees> 
16          <Fee Amount="0.00" Code="1" CurrencyCode="USD" TaxInclusive="false" Type="Exclusive"/> 
17        </Fees> 
18      </Rate> 
19    </Rates> 
20  </RoomRate> 
21  <RoomRate EffectiveDate="2025-01-12" ExpireDate="2025-01-13" NumberOfUnits="1" PromotionCode="EFR Winter Sale" RatePlanCode="202323288" RoomTypeCode="202323288">  
22    <Rates> 
23      <Rate EffectiveDate="2025-01-12" ExpireDate="2025-01-13" RateTimeUnit="Day" UnitMultiplier="1"> 
24        <Base AmountBeforeTax="300.00" CurrencyCode="USD"/> 
25        <Fees> 
26          <Fee Amount="0.00" Code="1" CurrencyCode="USD" TaxInclusive="false" Type="Exclusive"/> 
27        </Fees> 
28      </Rate> 
29    </Rates> 
30  </RoomRate> 
31</RoomRates>
32<Total AmountAfterTax="1355.70" CurrencyCode="USD"> 
33  <Taxes Amount="178.20" CurrencyCode="USD"> 
34    <Tax Amount="178.20" Code="27" CurrencyCode="USD" Type="Exclusive"/> 
35  </Taxes> 
36</Total>

Guest counts

Booking Notification and reservation retrieval manage the details of guest count similarly. The main difference is that Booking Notification uses the <AgeQualifyingCode> element to reference age category. Expedia Group uses the following OTA codes:

  • 8 for children (infants are treated as children)
  • 10 for adults 
1<GuestCounts IsPerRoom="true">    
2  <GuestCount AgeQualifyingCode="10" Count="2"/>    
3  <GuestCount Age="9" AgeQualifyingCode="8" Count="1"/>    
4  <GuestCount Age="17" AgeQualifyingCode="8" Count="1"/>    
5</GuestCounts>

Payment details

Payment details are managed very differently by Booking Notification 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 Notification 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<Guarantee>    
2  <GuaranteesAccepted>    
3    <GuaranteeAccepted>    
4      <PaymentCard CardCode="VI" CardNumber="4111111111111111" CardType="1" ExpireDate="0420" SeriesCode="123">    
5        <CardHolderName>Etienne Tester</CardHolderName>    
6      </PaymentCard>    
7    </GuaranteeAccepted>    
8  </GuaranteesAccepted>    
9</Guarantee>    
10<Total AmountAfterTax="955.49" CurrencyCode="CAD">    
11  <Taxes Amount="148.69" CurrencyCode="CAD">    
12    <Tax Amount="148.69" Code="27" CurrencyCode="CAD" Type="Exclusive"/>    
13  </Taxes>    
14</Total>

Reservation delivery and confirmation

The Booking Notification API pushes reservation details to a specified endpoint. In contrast, reservation management sends a notification when reservations are created and then you can use the reservations query to retrieve reservation details.

Reservation notifications

The notification service (also referred to as "webhooks") enables us to push real-time notifications to your app when asynchronous events occur. HTTPS is used to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your system.

Note: If multiple GraphQL capabilities are implemented, you may want to create multiple callback URLs where notifications are sent. For example, you could create one for reservation delivery events and one for reviews events. Click here for webhook notification details.

1<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">   
2  <soap-env:Header>   
3    <Interface xmlns="http://www.newtrade.com/expedia/R1/header" Name="ExpediaDirectConnect" Version="4.0">   
4      <PayloadInfo RequestId="22922694" RequestorId="Expedia.com" ResponderId="EQCSpecTest" ExpirationDateTime="2016-05-17T20:55:00+00:00" Location="Body">   
5        <CommDescriptor SourceId="ExpediaDC" DestinationId="EQCSpecTest" RetryIndicator="false">   
6          <Authentication Username="Expedia" Password="Password"/>   
7        </CommDescriptor>   
8        <PayloadDescriptor Name="OTA_HotelResNotifRQ" Version="2003A">   
9          <PayloadReference SupplierHotelCode="1154286" DistributorHotelId="1154286"/>   
10        </PayloadDescriptor>   
11      </PayloadInfo>   
12    </Interface>   
13  </soap-env:Header>   
14<soap-env:Body>   
15  <OTA_HotelResNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="22922694" PrimaryLangID="en-us" ResStatus="Commit" Target="Production" TimeStamp="2016-05-17T11:25:00-07:00" Version="1.000">   
16    <POS>   
17      <Source>   
18        <RequestorID ID="A-Expedia" Type="18"/>   
19        <BookingChannel Primary="true" Type="2">   
20          <CompanyName>Expedia</CompanyName>   
21        </BookingChannel>   
22      </Source>   
23    </POS>
24  </OTA_HotelResNotifRQ>
25</soap-env:Body>

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. For complete information regarding required fields, refer to Reservation delivery. 

1<soap-env:Body>   
2  <OTA_HotelResNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="tokennumber" Version="current version" ResResponseType="Committed" TimeStamp="datetime" Target="Production" PrimaryLangID="en-us">   
3    <Success/>   
4    <HotelReservations>   
5      <HotelReservation>   
6        <ResGlobalInfo>   
7          <HotelReservationIDs>   
8            <HotelReservationID ResID_Type="3" ResID_Value="ConfNumber123" ResID_Date="datetime" ResID_Source="EQCSpecTest"/>   
9            <HotelReservationID ResID_Type="8" ResID_Value="number" ResID_Source="Expedia" ResID_Date="datetime"/>   
10          </HotelReservationIDs>   
11        </ResGlobalInfo>   
12      </HotelReservation>   
13    </HotelReservations>   
14  </OTA_HotelResNotifRS>   
15</soap-env:Body>

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 that indicates a “CHANGE_REQUEST” in Booking Notification 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.

Booking Notification and reservation management indicate reservation changes similarly; they both push information indicating there has been a modification. However, with reservation management, a notification is sent that indicates that new reservation details are available. Booking Notification will simply send the new details.

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 made through the Booking Retrieval, Booking Confirmation, or Booking Notification API will not trigger future event notifications if a software connection is switched to a system that has implemented reservation management.
  • 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

Reservation management and Booking Notification 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 request. However, the error included in the message provides details and the line number where the error exists, which makes troubleshooting easier.

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

  • Booking Notification error codes Many of the error codes are related to header details; the header hosts the router details when a reservation is being sent. We refer to these as “nack error codes”. Refer to this detailed list for Booking Notification mapping errors.
  • 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.