Requirements and best practicesCopy link

This section highlights requirements and best practices to keep in mind when developing your Booking Retrieval and Booking Confirmation integrations.

If you are looking for information about capabilities offered by additional APIs, such as Products, Availability and Rates Retrieval, or Product API, refer to the overview page.

Development requirements

Before implementing Booking Retrieval and Booking Confirmation, make sure you meet these requirements:

• Have a reliable connection to the Internet
• Be able to initiate HTTPS connections to Expedia Group servers and provide authentication (username/password)
• Expedia will only accept request sent using TLS v1.2 protocol for PCI compliance
• Be able to generate XML documents conforming to API schemas (XSD)
• Be able to retrieve bookings (reservations, modifications and cancellations) using XML messages
• Be able to provide confirmation numbers for retrieved bookings (reservations, modifications and cancellations) using XML messages
• Be able to handle errors and warning scenarios as per this specification’s recommendations
• Abide by Expedia Group’s terms and conditions

XML requirements

All XML documents must be well-formed, adhere to the schema (XSD), and be encoded in UTF-8. In addition:

• Refer to the correct schema version: In the XML namespace attribute, @xmlns, ensure the schema version has been correctly updated. This ensures all expected functionality will be present, as not all versions support all features.
• When specifying empty XML elements, do not use self-closing tags. Example: <propertyName></propertyName>, not<propertyName/>
• Do not include HTML, markup language, or other miscellaneous tags within the XML
• If you need to preserve whitespace formatting, you can use CDATA sections in the XML. Only one CDATA section can be used per element, and nested CDATA sections are not allowed.

Security requirements

Booking Retrieval uses a secure endpoint provided by Expedia Group. You then call https://services.expediapartnercentral.com/eqc/br to retrieve booking information.

Booking Confirmation uses its own secure Expedia Group endpoint. You then call https://services.expediapartnercentral.com/eqc/bc to supply the property’s confirmation numbers.

Here are the general guidelines for Booking Retrieval and Booking Confirmation APIs:

• TLS 1.2 is required. SSL has been deprecated as a supported protocol and its use is not permitted for BR and BC integrations. Instead, use TLS to provide over-the-wire encryption (HTTPS)
• Be secured using basic authentication.

Minimum certification requirements

To adopt the Booking Request and Booking Confirmation API, you must successfully complete end-to-end certification with Expedia Group teams. You are expected to retrieve all bookings created, modified, or cancelled within a couple of minutes (as often as possible) and return a confirmation number in the response. Specifically, you must be able to support and show the following elements on your user interface:

• Business models: Expedia Collect, Hotel Collect, and Expedia Traveler Preference
• Payment models: Expedia Virtual Card (EVC) and Guest Credit Card
• Point of Sale (POS)
• Unicode (non-standard ASCII and accents), which is required in specific regions
• Promotion name
• Guest type (adult, child, and infant), count, and age
• Special requests 1-6 (Bedding, Smoking preference, Multi-room, Free text, Payment instructions, Value add promotions)
• Payment information (booking amount, tax, and fees)
• Masked email address for the guest
• Tax amount sent by Expedia accepted and honored in booking messages
• Error handling (warning and error codes displayed to the Lodging Partner)

Best practices

When designing the electronic interface used to connect to the Booking Retrieval API to retrieve bookings, you should make sure to read and understand the following guidelines, recommendations and best practices.

DO:

• Use Expedia Booking IDs to identify bookings
• Ensure the connectivity solution in use validates booking IDs to avoid duplicate bookings
• Use caution when re-retrieving bookings to avoid the possibility of overwriting newer manually entered information.
• Ensure monitoring is in place in the Booking Retrieval and Booking Confirmation APIs’ implementation to validate the success rate of updates including visibility in error details/messaging.

DON’T:

• Ignore warnings included with Booking Confirmation response messages.
• Ignore any errors that might be received. These may signal connection issues or problems with your request.

Expedia property and booking IDs

The Expedia property ID is defined by Expedia Group and uniquely identifies a property in the Expedia Group system, and mapped by supplier to code in the supplier’s system. IDs must be accurately mapped between your system and Booking Retrieval and Booking Confirmation APIs so properties receive the correct booking information.

The Expedia booking ID is the only unique key identifying an Expedia booking. The booking ID should be used to identify bookings when you retrieve booking modifications or cancellations. Do not reuse booking IDs from previous reservations; IDs must be unique. If a booking ID was created for an online or offline booking, Expedia Group will store that information in case there are changes to it. Ensure the connectivity solution in use validates booking IDs to avoid duplicate bookings.

It is crucial that you save this Expedia Booking ID in your system. Booking IDs must be used

• To identify existing bookings before creating new bookings
• As a key reference by the billing and reconciliation process

Localized content in quote and booking transactions

Travelers using Expedia.com or Hotels.com to make domestic bookings in China, Hong Kong, Japan, Korea, and Taiwan can enter their name and special requests in their local language at the time of booking.

To successfully implement this feature, both the property and connectivity systems need to support UTF-8 encoding, which is an international encoding standard for different languages. If either the property or the connectivity system do not support UTF-8, you can opt-out of this feature by contacting your Expedia Group Technical Relationship Manager or consider updating the integration to become UTF-8 compliant.

Bookings per BR request

To ensure consistent performance for both Booking Retrieval and your system, the Booking Retrieval API limits the number of bookings that can be returned on a single retrieval call.

When retrieving bookings, the maximum number that can be returned with one booking retrieval request is 125. If a request is made for pending bookings and more than 125 bookings are pending retrieval, the next retrieval request will return the remaining bookings.

Also, if you request all bookings made for a certain time period and more than 125 bookings occurred in that time frame, only the 125 most recent bookings will be retrieved.

Requesting previously retrieved bookings

Expedia Group offers different ways to re-retrieve booking messages that were previously retrieved.

Elements can be used to refine the bookings being retrieved for specific purposes. You can

• Retrieve all pending or retrieved bookings (using the Status element)
• Create a reconciliation job to only retrieve confirmed bookings made within the last 30 days for a specific property (using the NbOfDaysInPast, Status and Hotel ID elements)

You should use caution when implementing this function and compare the information they retrieve through the API with the information currently available in your systems to avoid the following scenarios:

• Properties might overwrite newer information manually entered in their systems with information provided by Booking Retrieval API.
• A property might duplicate the same booking it received earlier if the Expedia booking ID is not properly implemented in your system (see the Booking Confirmation overview for details). You should ensure your connectivity solutions validate booking IDs to ensure duplicate bookings are not created.

New reservations followed by modifications and/or cancellation

Booking Retrieval API issues new reservations, modifications and cancellations sequentially. Modification and cancellation notifications will only be issued after the respective new reservation is initially confirmed. A booking that has more than one transaction pending retrieval will only return the first booking transaction pending retrieval. As an example, for a booking that was initially created, then modified twice before any booking retrieval request is received:

• The new reservation will be returned first and is confirmed by Booking Confirmation (BC)
• Then "pending modification 1" will be returned with the next booking retrieval request after confirmation through BC
• After the second confirmation, the "pending modification 2" will be returned with the 3rd booking retrieval request

Booking updates are always retrievable sequentially after they are confirmed through Booking Confirmation.

Special request text and booking modifications

Bookings can include a special request, entered in free-form text (RequestCode="4"). This information is included in the booking response (BR RS) message for a booking alongside all other details.

However, if the booking is subsequently modified, the corresponding BR RS message will replace the original text with the modified one. Booking Retrieval responses will only send the most recent special request text.

You may need to add the new or modified special request text within your systems for updated bookings if you find it valuable to keep a history of these requests.

Confirm bookings retrieved with Booking Retrieval API

You need to use the Booking Confirmation API to confirm bookings retrieved with BR API including all reservations, modifications, and cancellations.

Confirmation numbers need to be received before the bookings expire. Unconfirmed bookings will revert to email once the booking expiration time is reached.

Expedia Group’s booking expiration strategy is based on booking window:

• Same-day arrival (based on midnight in property’s local time zone): bookings will expire 30 minutes after their creation by customer.
• Next-day arrival (any bookings created between midnight and 23:59:59 the day before arrival, based on the property's local time zone): bookings will expire 60 minutes after their creation by the customer.
• For any longer booking window, bookings will expire 24 hours after their creation by the traveler.

Booking confirmation numbers can be updated for previously confirmed bookings up to 8 days after the guest's departure date.

Hotel Collect and Expedia Collect

Expedia supports different business models. To understand how bookings reflect the different business models (ExpediaCollect, HotelCollect), please see the outline below.

Different Rate Plan ID

Different Rate Value

Point-of-sale details

Expedia Group has a number of brand sites and points of sale where customers from all over the world can book the inventory you are supplying. In order to ensure the guest experience is managed properly it’s important that the below Point of Sale Brand names are consumed within the BR API and passed down to front desk systems so that guests can be properly greeted upon arrival.

Here are the different point-of-sale values:

Different Payment card information