Requirements and best practicesCopy link

This section highlights requirements and best practices to keep in mind when developing your Availability and Rates API integration.

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

Development requirements

Before implementing Availability and Rates API, 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 connect using the providedExpedia Group URL. Expedia Group does not support connection to the API directly via IP address, as this address is subject to change without notice.
• If you prefer IP addresses for communication performance reasons, you may consider implementing an address caching strategy to reduce DNS lookups for the URLs.
• If you whitelist outbound connections, you must do so using a URL pattern rather than an IP range, as Expedia Group cannot guarantee a specific IP range/subnet.
• Be able to generate XML documents conforming to the API’s schemas (XSD)
• Be able to send changes to rates and availability using XML messages
• Use either Booking Retrieval and Booking Confirmation APIs or Booking Notification API to
  • Be able to retrieve or receive bookings (reservations, modifications and cancellations) using XML messages
  • Be able to provide confirmation numbers for bookings (reservations, modifications, and cancellations) using XML messages
  • Be able to troubleshoot errors and warning scenarios according to this specification’s recommendations
• Abide by Expedia Group’s terms and conditions

You also have the option of retrieving products, availability and rate data using Partner Central. Product API retrieves product information only with JSON, but does not provide availability or rates information.

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. Example:
  • Elements follow the upper camel case (UCC) convention while attributes follow the lower camel case (LCC) convention.
  • Information is found mostly in attributes. Elements are used only to structure the information and make logical groupings.
• If an element contains text, the text was entered manually.
• Validation rules about data type, data format, and data size and length are included in the schema.

Security requirements

Availability and Rates integration uses a secure endpoint provided by Expedia Group. You call https://services.expediapartnercentral.com/eqc/ar to send all availability and rates information.

Here are the general guidelines for Availability and Rates integration:

• TLS 1.2 is required. SSL has been deprecated as a supported protocol and its use is not permitted with integrations to Expedia Group systems. Instead, use TLS to provide over-the-wire encryption (HTTPS). Note that Expedia Group’s servers are not configured to accept posts over unsecured HTTP.

• Be secured using basic authentication. Note that anyone with development questions or that has not worked with Expedia Group before should contact us.

Minimum certification requirements

Partners who want to adopt the Availability and Rates API are required to successfully complete end-to-end certification with Expedia Group teams. You are expected to automatically update rates and availability up to two years in advance, and you must be able to support and show the following elements in your user interface:

• Set real-time room availability updates
• Perform a close out at the room or rate plan level and send an updated room inventory count of 0
• Update rates based on the set of pricing models offered (PDP, OBP, or PDP+LOS)
• Set minimum or maximum length-of-stay and closed-to-arrival/ departure restrictions for a single date or a date range

Best practices

Keep the following best practices in mind:

• Unique IDs: The property ID is defined by Expedia Group and uniquely identifies a property in the Expedia Group system, which you map to the property code in your system. IDs must be accurately mapped between your system and Availability and Rates API so the correct properties are updated.
• Room and rate IDs: You must also ensure the correct Expedia Group room and rate IDs are accurately mapped in your implementation of Product API to make sure the right rooms and/or rate plans are updated when the API sends updates.
• XML schema development: The design of the API schemas is based on several general guidelines.
• Information is found mostly in attributes, elements are used to structure the information and make logical groupings. Note that if an element contains text, it is most likely because the text was entered manually.
• Validation rules about data type, data format and data size/length are included in the schema and should be incorporated during development.
• Expedia uses namespaces to version its schemas. Messages sent to Expedia Group systems should always contain the proper namespace.
• Boolean will be returned as "true" or "false".

When designing the electronic interface used to connect to Expedia Group servers to update availability and rates, you should make sure to read and understand the following guidelines, recommendations and best practices.

DO:

• Use Expedia room and rate IDs to identify correct rooms and rate plans to be updated.
• Ensure your system can synchronize the property by triggering updates that send all rate and availability information for at least the next rolling 500 days.
• Use caution when sequencing messages to Expedia Group - sending an older message after a newer message can overwrite current information with out-dated data.
• Ensure monitoring is in place in the Availability and Rates (AR) implementation to validate the success rate of updates, including visibility in error details/messaging.

DON’T:

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

Rate limits

If you receive the HTTP 429 status code, we recommend implementing an exponential backoff and retry mechanism to avoid overwhelming our services. In an effort to protect our platform, we may adjust the limit based on the assessment of incoming traffic to our systems. If you have questions, contact your Expedia Group Technical Relationship Manager who can provide guidance and address any concerns.

Monitoring

You should ensure monitoring is in place for your interface implementation so the ratio of successful Availability and Rates updates is visible and can get detailed information on any errors or warnings. Alarms should also be created to notify you when the rate of message errors or warnings returned by Expedia Group exceeds an acceptable threshold. It is recommended that an alarm be triggered when any type of message returns errors or warnings at a rate of 10% or more. You should review errors and warnings frequently to ensure that bookings are received and confirmed, and that all updates are processed correctly. Failure to do so may result in Expedia Group booking rooms at the incorrect price or already sold out, or bookings to fall back to email if not confirmed.

Responses may contain more than 20 warnings. When messages fail various Expedia Group validations, Expedia will return up to twenty warnings per type of problem.

You should solve the problems reported and attempt to resend the information to Expedia Group again. If needed, it is possible to obtain the full list of warnings that the request generated, if the request is answered within 30 days of the message creation date. For more details, please contact us.

Synchronizing availability and rates

For many different reasons, it is possible for Expedia Group and its partners to have their rates and/or availability fall out-of-synch. When a property is first activated on an Expedia Group API, your system and Expedia Group’s systems should be synchronized.

Your system therefore requires a function that can synchronize the property by triggering updates that send all the information about rates and availability for at least the next 365 days. Also, you could experience system degradation and lose track of which updates were already sent to Expedia Group. It might then become necessary to perform a resync of availability and rates for specific products and dates. Several parameters should be configurable before triggering synchronization:

• The interval of dates on which to perform the synchronization
• Which room type ID(s) (one or more, possibly a list)
• Which rate plan ID(s) (one or more, possibly a list)

Updating room types and rate plans

Room type refers to the basic bed type arrangements and smoking preference. Details include the number of guests allowed per room.

Note that bedding type and smoking preference as well as other content about the rooms including various fees charged on-site can be updated with Partner Central orProduct API. Rate plan creation and many rate plan modifications not supported in Availability and Rates API can be done with Partner Central or Product API as well.

Rate plans are a set of attributes that describe the pricing information for a room type including room rate and various fees, as well as describe how room types can be sold (e.g. cancellation policies and length-of-stay restrictions). Room types can have multiple rate plans.

You will develop and maintain mapping between your properties’ room and rate codes and Expedia Group’s equivalent room type and rate plan IDs. This mapping is critical for sending updates because you must specify the Expedia ID in its XML messages, not the property’s codes.

Example: Room type code STD in the property’s system maps to a unique room type ID 1093294 in Expedia Group’s system.

Whenever properties change their room or rate codes, or request new products to be created, you must update the mapping of the property’s codes in its system with Expedia Group’s equivalent new or existing IDs to maintain successful communication of availability updates and booking notifications between you and Expedia Group.

The Expedia Group product mapping can be obtained electronically with Product API, or manually with Partner Central. The Expedia Group room type and rate plan IDs are alpha-numeric, and the relationship between room type and rate plan is a one to many hierarchy. In Partner Central, use the Room and Rate Plan Summary page to look up a property’s room and rate plan names to determine Expedia Group’s equivalent IDs.

Sending availability and rate updates to Expedia Group

To keep Expedia Group in sync with the property’s availability and rates, updates should be triggered by the property’s system as soon as rates, availability, or restrictions change.

Expedia Group expects to receive per day, on average, approximately 180 updates per product (i.e. room type), per property. Typical properties connected through the API, with about 10 room type/rate plan combinations on average, can send up to 5,000 updates per property, per day.

Counting the number of updates included in a message

Expedia Group has specific rules around message bundling specifically related to how many updates are included in any single message. Each message can contain no more than 5000 updates.

The update count of an Availability and Rates (AR) message is defined as the number of distinct data elements being changed by that message. Each individual rate, restriction, or status change for one stay date is counted as one update.

Example:

The following message contains three updates - number of rooms, a rate, and a closed-to-departure restriction (unavailable for guests searching for checkout on this date) for one day.

1<AvailRateUpdate>
2  <DateRange from="2019-08-01" to="2019-08-01"/>
3  <RoomType id="9989">
4    <Inventory totalInventoryAvailable="50"/>
5    <RatePlan id="556895">
6      <Rate currency="EUR">
7        <PerDay rate="55.00"/>
8      </Rate>
9      <Restrictions closedToDeparture="true"/>
10    </RatePlan>
11  </RoomType>
12</AvailRateUpdate>

The following excerpt contains 1098 updates - number of rooms, a rate, and a closed-to-departure restriction (unavailable for guests searching for checkout on this date) for 365 days.

1<AvailRateUpdate>
2  <DateRange from="2019-08-01" to="2020-07-31"/>
3  <RoomType id="9989">
4    <Inventory totalInventoryAvailable="50"/>
5    <RatePlan id="556895">
6      <Rate currency="EUR">
7        <PerDay rate="55.00"/>
8      </Rate>
9      <Restrictions closedToDeparture="true"/>
10    </RatePlan>
11  </RoomType>
12</AvailRateUpdate>

Combining multiple updates in a single message

To reduce the number of messages sent to Expedia Group systems, you can use multiple <AvailRateUpdate> elements in one message and leverage the ability to specify multiple date ranges, room types, and rate plans in the same message. Multiple updates can be bundled into a single Availability and Rates message, as below.

1<?xml version="1.0" encoding="UTF-8"?>
2<!-- Sample AR request message: multiple AvailRateUpdate elements-->
3<AvailRateUpdateRQ xmlns=" http://www.expediaconnect.com/EQC/AR/2011/06 ">
4    <Authentication username="testuser" password="testpass"/>
5    <Hotel id="3546"/>
6    <AvailRateUpdate>
7        <DateRange from="2019-08-01" to="2019-08-01"/>
8        <RoomType id="558875" closed="false">
9            <Inventory totalInventoryAvailable="10"/>
10            <RatePlan id="556895">
11                <Rate currency="EUR">
12                    <PerDay rate="100.00"/>
13                </Rate>
14                <Restrictions closedToArrival="false" closedToDeparture="false" minLOS="2" maxLOS="7"/>
15            </RatePlan>
16        </RoomType>
17    </AvailRateUpdate>
18    <AvailRateUpdate>
19        <DateRange from="2019-08-01" to="2019-08-01"/>
20        <RoomType id="558875" closed="false">
21            <RatePlan id="665456">
22                <Rate currency="EUR">
23                    <PerDay rate="150.00"/>
24                </Rate>
25                <Restrictions closedToArrival="false" closedToDeparture="true" minLOS="1" maxLOS="14"/>
26            </RatePlan>
27        </RoomType>
28    </AvailRateUpdate>
29    <AvailRateUpdate>
30        <DateRange from="2019-08-01" to="2019-08-01"/>
31        <RoomType id="558875" closed="false">
32            <RatePlan id="98789">
33                <Rate currency="EUR">
34                    <PerDay rate="180.00"/>
35                </Rate>
36                <Restrictions closedToArrival="false" closedToDeparture="false" minLOS="1" maxLOS="7"/>
37            </RatePlan>
38        </RoomType>
39    </AvailRateUpdate>
40    <AvailRateUpdate>
41        <DateRange from="2019-08-01" to="2019-08-01"/>
42        <RoomType id="99677" closed="false">
43            <Inventory totalInventoryAvailable="10"/>
44            <RatePlan id="35345">
45                <Rate currency="EUR">
46                    <PerDay rate="110.00"/>
47                </Rate>
48                <Restrictions closedToArrival="false" closedToDeparture="false" minLOS="1" maxLOS="7"/>
49            </RatePlan>
50        </RoomType>
51    </AvailRateUpdate>
52    <AvailRateUpdate>
53        <DateRange from="2019-08-01" to="2019-08-01"/>
54        <RoomType id="99677" closed="false">
55            <RatePlan id="342223">
56                <Rate currency="EUR">
57                    <PerDay rate="145.00"/>
58                </Rate>
59                <Restrictions closedToArrival="false" closedToDeparture="false" minLOS="1" maxLOS="14"/>
60            </RatePlan>
61        </RoomType>
62    </AvailRateUpdate>
63</AvailRateUpdateRQ>

Preventing duplicate updates

The property must ensure that only new updates are being sent, not information that has already been transmitted to Expedia Group. It would be poor practice to send a property’s entire Expedia Group availability every day. Messages should only be sent to keep Expedia Group synchronized with changes on the property’s system. Avoiding redundant updates will also ensure that necessary updates are processed faster, since each update is handled sequentially and

• Expedia Group systems only allow one connection open per product (room type & rate plan combination) for the same stay date at a time.
• Processing one message can be a lengthy process, taking up to 5 seconds.

Sequencing/ordering messages

Sequencing of messages (order in which you send messages and then processed by the API) is critical. You should ensure that messages for Expedia Group are sent in the right order so that the system is not updated with outdated information. Since the Expedia Group systems process requests synchronously, an older message sent after a newer one would be processed in the order it is received, potentially overwriting more up to date information in the system. Therefore, it is important that you take extra care when designing your solution to make sure this cannot happen in your systems.

Managing inventory

Inventory is the main component of availability and makes up the base information carried in availability messages. Inventory indicates the total amount of available products (e.g. if Room Level inventory is 5, it can only be booked 5 times).

Properties can manage their rates and availability for up to two years in advance. However, you should use caution when using long date ranges in a single Availability and Rates request message. Long date ranges imply many updates per message and Expedia Group limits the number of updates per message to a maximum of 5000 updates per message.

Availability changes related to Expedia Group bookings

Whenever Expedia Group books or cancels a room, the property system interface to Expedia Group’s servers should NOT update the number of rooms available for sale on Expedia Group as this will be updated automatically by Expedia Group. For example, if the property receives a booking for room type ID "111" for December 24th 2016 to December 26th 2016 from an Expedia Group point-of-sale, the property should NOT send a decrement of 1 room for the room type "111" for December 24th and December 25th 2016. Expedia Group is already aware.

For more information about closing rate plans or closing room types to avoid overbookings, see their related articles.

Closing rooms to avoid overbookings

To close a room that is still available on Expedia Group, always send a close message for the room type along with setting the number of available rooms @totalInventoryAvailable or @flexibleAllocation to zero. Sending zero (0) will not completely close the room type and, in the case of cancellation, the room will become available again on Expedia Group.

Coding to the correct pricing model

When developing for the Availability and Rates API, make sure you develop the correct pricing models for your customers. Currently Expedia offers several different pricing models: occupancy-based pricing (OBP), per-day pricing (PDP), day-of-arrival pricing (DOA), and per-day length-of-stay pricing (LOS).

For more details, see Pricing models.

Closing rate plans

Properties typically use more than one rate plan to sell a room. One important reason for multiple rate plans is that rates needed to sell rooms for standalone bookings (room-only) are different from those needed for package bookings (room + flight/car/train) or corporate bookings (bookings through the Egencia point-of-sale). As a result, properties usually have both standalone and package versions of a rate plan configured, such as: Room Only (S), Room Only (P) and Room incl. Breakfast (S), Room incl. Breakfast (P).

Managing rates for a property using occupancy-based pricing

If you want to change the occupancy levels in the room, you first have to contact your Market Manager to change the configuration of the room type (thereby updating the property’s settings on Partner Central), and then you have to send Expedia Group the new rates for those occupancy levels.

Occupancy-based pricing also requires the rate to be set to the total amount charged for that occupancy level. For example, if a property already has occupancy level 4 newly configured for it on Partner Central and wants to set the rate for occupancy level 4 of a room type to $160.00, then it should include the following input in the Availability and Rates request (AR RQ) message:

The Availability and Rates API currently does not support removal of occupancies.

Sending the right type of rate to Expedia: sell rate, net rate or lowest available rate

Expedia Group accepts receiving sell rate, net rate, or lowest available rate (LAR) for rate updates through the Availability and Rates API, and the type of rate to send to Expedia Group must be in sync with the configuration in Expedia Group’s system. Please verify which type of rate is being used to update Expedia Group products using Product API, Availability, Rate and Inventory API, or log on to Partner Central and consult product information there.

It is critical for you to define the right type of rate to upload because there will not be any validation done on the Availability and Rates API interface to confirm the rate sent has the right type. Sending the wrong rate will either make Expedia Group rate much lower than the property’s desired rate (when sending a net rate for a sell rate or lowest available rate-based product), or much higher (when sending a sell rate or lowest available rate for a net rate-based product).

Check the article in the Learn section for more details about net rates and sell rates.

Managing linked rate plans

For products with rate plan linkage rules in place and effective on a set of stay dates, you are not allowed to update the child products’ rates for those dates. Restrictions are not expected to be managed either if they are linked. Child rate plans with linkage rules cannot be managed over Availability and Rates API when a rule is effective for the stay dates being updated. Only the parent rate plan can be managed: Expedia Group will automatically derive rates and restriction updates to the child.

If you attempt to manage rates and/or restrictions on a rate plan where a rate plan linkage rule exists, the Availability and Rates service will return a successful response, but will ignore the updates received on the child.

See Linking rate plans for more information.

Using day of week attributes with date ranges

Day of week attributes can be used when you want to perform updates based on the day of the week. For example, you might want to update rates for Friday, Saturday and Sunday, for the month of August 2019. To do so, it is not necessary to call out every single date needing to be updated. Instead, day of week attributes can be used.

As soon as day of week attributes are used, updates will only be applied to the attributes for which the value is set to true. Missing or omitted day of week attributes will see their value defaulted to false. When using day of week along with date ranges, Expedia Group recommends always specifying all 7 attributes, with their desired value (true for days requiring an update, false for days that shouldn’t be updated). This is the safest way for you to ensure Expedia Group will interpret their updates the desired way.

Sample AR request message - updating rates for 1 room type and 1 rate plan every weekend of the month of August 2019:

1<AvailRateUpdateRQ xmlns="http://www.expediaconnect.com/EQC/AR/2011/06">
2  <Authentication username="testuser" password="testpass"/>
3  <Hotel id="3547"/>
4  <AvailRateUpdate>
5    <DateRange from="2019-08-01" to="2019-08-31" mon="false" tue="false" wed="false" thu="false" fri="true" sat="true" sun="true"/>
6    <RoomType id="558025">
7      <RatePlan id="556895" closed="false">
8        <Rate currency="EUR">
9          <PerOccupancy rate="80.00" occupancy="1"/>
10          <PerOccupancy rate="120.00" occupancy="2"/>
11        </Rate>
12      </RatePlan>
13    </RoomType>
14  </AvailRateUpdate>
15</AvailRateUpdateRQ>

Setting a minimum and maximum length-of-stay

Expedia Group supports two different methods to apply minimum and maximum length of stay restrictions. Minimum and maximum length-of-stay are property-level settings in Expedia Group’s system, and any Expedia Group Market Managers can modify this setting.

Arrival-based restrictions:

Minimum and maximum length of a booking where the system calculates by reading the Length-of-Stay (LOS) configured for the requested arrival date.

Stay-through based restrictions:

Minimum and maximum length of a booking where the system calculates by reading all days of the requested stay and applying the most restrictive values from any of those days.

Restricting updates beyond a certain minimum length-of-stay value

Expedia Group will not accept updates past a certain minimum length-of-stay value. When a property exceeds the maximum value allowed per Expedia Group configuration, it will receive the following error:

3135: MinLOS value ([value specified in message]) exceeds Extranet auto-approval threshold ([configuration for this property in Expedia system]) for length of stay. This is a setting that is configured on a per-property basis in Expedia Group’s system.

Minimum length of stay (MinLOS) and maximum length of stay (MaxLOS) can be updated using the Product API. If you are not using the Product API, contact your market manager to make changes to the minimum or maximum length of stay.