Requirements and best practicesCopy link

This section highlights requirements and best practices to keep in mind when developing your Booking Notification integration.

If you are looking for information on additional API capabilities, such as Image API or Product API, refer to the overview page.

Development requirements

Before implementing Booking Notification API, make sure you meet these requirements:

• Have a reliable connection to the Internet
• Be able to receive HTTPS connections from Expedia Group servers
• Use TLS v1.2 protocol for PCI compliance
• Be able to generate XML documents conforming to API schemas (XSD)
• Be able to provide confirmation numbers for received bookings (reservations, modifications and cancellations) using XML messages
• Be able to handle errors 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. (UTF-8 is required if you support Unicode names and special requests). 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 Notification API uses endpoints you provided.

Here are the general guidelines for Booking Notification API:

• TLS 1.2 is required. SSL has been deprecated as a supported protocol and its use is not permitted for Booking Notification (BN) integrations. Instead, use TLS to provide over-the-wire encryption (HTTPS).
• You must provide an endpoint for your test environment as well as a production environment.
• Be secured using basic authentication.
• Anyone receiving Hotel Collect notifications with credit card information must be PCI compliant. See PCI Compliance for more details.

Minimum certification requirements

To adopt the Booking Notification API, you must successfully complete end-to-end certification with Expedia Group teams. You are expected to acknowledge and accept all bookings created, modified, or cancelled and return 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
• Accept and honor any tax amount sent by us in the booking message
• Error handling (warning and error codes)

Best practices

When designing the electronic interface used to connect to the Booking Notification API to receive 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
• Ensure monitoring is in place in the Booking Notification (BN) implementation to validate the success rate of updates, including visibility in error details/messaging.

DON’T:

• Reject bookings, modifications, or cancellations sent in Booking Notification request messages from Expedia Group. All request messages must receive a response with a confirmation number or an error code.

Expedia property and booking IDs

The Expedia property ID is defined by Expedia Group and uniquely identifies a property in the Expedia Group system, which you map to the code in your system. Property IDs must be accurately mapped between your system and Booking Notification API so properties receive the correct booking information.

The Expedia booking ID is the only unique key identifying an Expedia booking. The booking ID is referred to with the <UniqueID> element @ID attribute in the Booking Notification specifications. 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.

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

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

Partner IDs

Partner IDs identify you within the Expedia Group system and are used in the Booking Notification messages. Expedia Group may assign more than one Partner ID per partner, specifically in cases where a partner uses multiple central reservation systems (CRS), but XML messages will only include one partner ID per message. Expedia Group will apply monitoring and take actions during outages based on partner IDs. To maximize your availability on Expedia Group, you should support multiple Partner IDs where appropriate.

Book with locally stored inventory and rates

Expedia Groups’s partners control availability, rates and inventory information with the Availability and Rates (AR) interface or Partner Central. Because you are able to provide the latest changes to availability or rates in real time with either an API service or Partner Central, Expedia Group allows customers to book against the most recent information received successfully and stored locally in Expedia Group’s systems.

The reservations sent with the Booking Notification API are notifications, made after the booking has been confirmed to the guest. You cannot reject these reservation notifications. Inventory issues are not an acceptable reason to reject a booking since these are avoidable if you update their inventory regularly.

The reservation notification request message will contain the property’s daily rates and may include taxes and extra person and extra service fees. If there are rate issues with the booking, this discrepancy should be flagged and the booking should be routed by the property to the staff member responsible for reconciling these differences and the Expedia Group Market Manager should be alerted. Pricing discrepancies are not acceptable reasons to reject a booking either. You are responsible for keeping your inventory and rates up to date.

We foresee two key standard cases where rates sent by Expedia Group may not match those in your system:

• The property’s staff member who manages updates rates on the Expedia Group system through the Availability and Rates (AR) API or Partner Central does not get a chance to update the rates in the property’s system before bookings with the new rates start to hit the system (or vice versa). When a human is entering data on two different systems that are actively sending and receiving bookings, it is not possible to ensure that the rates in every booking will be in sync. Such discrepancies should be minimized by using the Availability and Rates (AR) API or Partner Central.
• You decide to take advantage of Expedia Group’s promotional capabilities for a period of time. In Expedia Group’s system you can set up a special promotion to give "5th night free if you stay 4 nights". Those 5th nights that have a daily rate of $0.00 may not match the rate expected by the property’s system.

Potential duplicate booking scenarios

This section describes two possible scenarios related to potential double bookings in your system. The situations where potential duplicate bookings may occur happens when Expedia Group does not receive a valid response from you even though you have received the request and successfully processed the notification.

Since your response failed to transmit successfully, Expedia Group sends a email to the property. At the property, the person who receives the email could be trying to enter the reservation into their local system while Expedia Group is attempting to deliver the same booking to the property. If this happens, the staff member manually enters the reservation in their system and then attempts to enter the confirmation number with Partner Central.

• First scenario: Expedia Group also successfully delivered the booking and the supplier has returned a confirmation number to Expedia Group’s system. In this case, the staff member at the property will see a confirmation number for this booking already exists in Partner Central. At that point, they can delete the duplicate booking in their system on their own.
• Second scenario: The staff member enters the confirmation number through Partner Central before Expedia Group receives a confirmation number in the electronic response from you.In this case, Expedia Group’s system will automatically detect the double booking. Expedia Group monitors a log and will contact the property. If you subscribe to these reports, your point of contact will receive the report so the duplicate booking can be removed.

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, the partner can opt-out of this feature by contacting their Expedia Group Technical Relationship Manager or consider updating the integration to become UTF-8 compliant.

Free text in booking modifications (special requests)

Bookings can include a special request, entered in free-form text (RequestCode="4"), which is included in the booking notification request <OTA_HotelResNotifRQ> message for a booking alongside all other details.

However, if the booking is modified later, the corresponding Booking Notification request <OTA_HotelResModifNotifRQ> message, will send special request information only sent if a new special request is entered as part of the current modification. In other words, the modification notification request will not contain any previous special request information for modified reservations. Booking notification requests with modifications will only send the most recent special request text.

You should add any new free-form text special requests to the existing special requests saved in your system for the same reservation.

Booking Notification expiration time

When Expedia Group initiates a booking notification and creates a request message, a notification expiration date/time is set and sent in the message header. The notification time may be set to a fixed value of 2 hours 30 minutes from the notification creation time, or calculated based on the date of arrival of the booking, which is configurable per partner.

The purpose of the notification expiration time is to make sure that all possible message delivery attempts between systems are made before giving up on electronic delivery of the notification.

The expiration time is sent for information purposes only and you should not stop the notification from processing if the notification expiration time is reached or exceeded. Expedia Group will accept response messages after the notification has expired.

Until the notification has been completely processed (i.e. Expedia Group has received a valid response message with confirmation or error message), the notification expiration time will be monitored by Expedia Group to make sure it hasn’t expired. If the notification expires, then a email notification will be sent to the property or to the central reservation office.

Guarantees/credit cards included in booking messages

For Expedia Collect bookings paid by Expedia Virtual Card or Hotel Collect bookings paid with a guest credit card, the payload for Booking or Modify requests will include the <Guarantee> element as the container for credit card payment information.

• The <Guarantee> element will contain the credit card payment information including card type, card code, card number, expiry date, card holder name.
• For ExpediaCollect EVC bookings, a billing address is included, which is Expedia's head office address by default for all cards.
• In certain regions, the EVC cardActivation element will also be sent, representing the date and time the virtual card will become available for use. You should be able to process notification with or without the cardActivation element.
• For Hotel Collect bookings, depending on the property configuration Expedia Group may or may not send CVV for guest credit card, therefore the property booking notification interface must be able to process reservations both with and without CVV. The customer billing address is not included. To receive customer credit card information, partners receiving Hotel Collect notifications must be PCI-compliant.
• The element is optional and will be sent only for Expedia Collect bookings paid by Expedia Virtual Card, and for Hotel Collect bookings. For Expedia Collect bookings remaining on standard billing processes, no credit card information will be sent in the booking or modify request.

A special request code (5) is sent to communicate payment related information in booking or modify requests, for bookings paid by credit card, either Expedia Virtual Card or Hotel Collect. Please note that credit card information is only sent for the booking or modify requests, not for cancellation requests. Penalty charges, if applicable, should be processed using the same payment information sent with the original reservation. So, if the original reservation is sent with a credit card, the penalty charges should be put on the same card.

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 Booking Notification API and passed down to front desk systems so that guests can be properly greeted upon arrival.

For example:

1<POS>
2  <Source>
3    <RequestorID Type="18" ID="Hotels.com"/>
4    <BookingChannel Type="2">
5      <CompanyName>Expedia</CompanyName>
6    </BookingChannel>
7  </Source>
8</POS>

The current values are listed in the table below, but they may change in the future, so you should ensure these values are configurable.

A set of new values will be sent in the e-notification message for Hotel Collect bookings, which will be prefixed by "A-" in front of the current values for the respective points of sale.

For example, Hotel Collect bookings made on Hotels.com points of sale, the <POS> ID value will be "A-Hotels.com".

You must ensure proper mapping is done for the new <POS> ID values in your system so that Hotel Collect bookings can be associated with the appropriate profile.

Here are the different point-of-sale values: