Shopping
The Shopping API provides you with access to live rates and availability for 700,000 global accommodations.
Overview
The Shopping API returns rates and availability on all room types for specified properties (maximum of 250 properties per request). The response includes rate details such as promos, whether the rate is refundable, cancellation penalties, and a full price breakdown to meet the price display requirements for your market.
Multiple rooms of the same type may be requested by including multiple instances of the occupancy parameter. If the same occupancy is requested multiple times in the same request, the response will only contain a single set of rates for that occupancy. No more than 8 rooms may be requested at a time. If you need to book more than 8 rooms at once, please consult with your account manager about our group booking partnership.
Price display changes
Please be advised of recent changes due to local regulations:
- California Price Display Regulation (California Assembly Bill 537) that is effective from 2024-07-01
- Minnesota Price Display Regulation (Chapter 111--H.F.No. 3438) that is effective from 2025-01-01
We expect other regulations to come and will not be updating this page for each one, these are just two examples.
Why the changes?
Certain jurisdictions are implementing laws mandating how rates are displayed for travelers. Each law is slightly different, however, the way we have implemented the changes will allow for individualized compliance.
Expedia Group has made changes to its API to enable API partners to display pricing in a variety of ways. Ultimately, however, each partner using Expedia Group’s API is responsible for ensuring that the way it displays Expedia travel information and pricing complies with the law.
What are the changes?
Expedia has enhanced the Rapid API to include a new field property_inclusive containing total price that includes the base rate and all Expedia and property collected fees and taxes for the entire stay. A strike through version of this total price is also available in a new field property_inclusive_strikethrough. In addition to the new property inclusive display fields, we have realigned the way that taxes and fees are broken out in the API response. All Expedia collected fees are part of the nightly and stay property_fee price breakout type, and all Expedia collected taxes are part of the nightly and stay tax_and_service_fee price breakout type.
For Expedia Collect rates, the billable_currency of the property_inclusive and property_inclusive_strikethrough fields will be in the currency specified in Expedia Group’s contract with the supplier, which is usually the property's local currency. This is regardless of the request_currency, because the property_inclusive and property_inclusive_strikethrough fields may include fees collected at the property in the local currency. This behavior differs from the inclusive and inclusive_strikethrough fields, where the billable_currency for Expedia Collect rates will be the same as the request_currency.
The Shop response may have the property collected amounts grouped differently than the amount presented in the Content response. The totals should still match correctly.
This was a global change implemented to all properties, please contact your account manager for any further questions on the changes.
Loyalty points
Properties with loyalty schemes that participate in Expedia’s business rate program offer the opportunity for business travelers to earn hotel loyalty points for their stays. Partners can use the amenities node of the Shopping response to identify and showcase loyalty eligibility prior to the capture of membership details from the traveler.
Partners can also specifically search for loyalty eligible business rates by using the loyalty value filter in their Shopping API requests.
Note: Loyalty point earn is only available on business rates where the hotel has an existing loyalty program.
Example:
Hotel business rates eligible for loyalty points will have the following parameter in the search response under the amenities node
{
"id": "2096",
"name": "Eligible for hotel loyalty points"
}Commission incentives
As a Rapid API partner, you have access to additional commission incentives that offer higher margins on properties for a designated book and stay date period. To identify properties with an active commission incentive, simply use the rooms.rates.marketing_fee_incentives value for the include parameter in your Rapid Shopping API request. Rates with commission incentives for all or a portion of the requested stay period will have additional details, including the source of the incentive and the portion of the stay affected, in the marketing_fee_incentives object in the Shopping API response. You can then consider this and the existing marketing_fee field, which is an estimate of the marketing fee that includes all available incentives, in your inventory sort and selection process.
Example
Property 19248 is offering higher margins for stays in December. Make a Shopping API request for property 19248 for a stay from December 22 to January 5. In the marketing_fee_incentives object of the Shopping API response you will see that there is an incentive available for a portion of the requested stay from December 22 to December 31, which represents 10 of the 14 stay nights.
Example request
curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2023-12-22\
&checkout=2024-01-05\
¤cy=USD\
&country_code=US\
&language=en-US\
&occupancy=2\
&property_id=19248\
&rate_plan_count=1\
&sales_channel=website\
&sales_environment=hotel_only\
&include=rooms.rates.marketing_fee_incentives\
&travel_purpose=leisure" \
-H "accept: application/json, application/json"\
-H "accept-encoding: gzip"\
-H "authorization: EAN apikey=abcd1234,signature=090a77e7ddd7779980231,timestamp=1697664047"\
-H "user-agent: TravelNow/3.30.112"Example response
[
{
"property_id": "19248",
"rooms": [
{
"id": "123abc",
"room_name": "Fancy Queen Room",
"rates": [
{
"id": "333abc",
...
"marketing_fee_incentives": [
{
"source": "property",
"start": "2023-12-22",
"end": "2023-12-31"
}
],
"occupancy_pricing": {
"2": {
"nightly": [ ... ],
"stay": [ ... ],
"totals": {
"inclusive": { ... },
"exclusive": { ... },
"inclusive_strikethrough": { ... },
"strikethrough": { ... },
"marketing_fee": {
"billable_currency": {
"value": "276.36",
"currency": "USD"
},
"request_currency": {
"value": "276.36",
"currency": "USD"
}
},
"gross_profit": { ... },
"minimum_selling_price": { ... },
"property_fees": { ... }
},
"fees": { ... }
}
}
}
]
}
]
}
]Travel purpose
The travel_purpose parameter allows you to designate your travel as business or leisure. Starting April 1, 2024 partners who are eligible to shop for business rates will need to use travel_purpose=business in the Shop request to receive business rates in the Shop response. If no travel_purpose parameter is given in the request then leisure will be assumed and no business rates will be returned.
Example
Specifying that the traveler is intending to travel for business purposes is as easy as adding 24 characters to the Availability API request.
&travel_purpose=businessStrikethrough pricing
- The
strikethroughfield provides the tax exclusive total price before any hotel-funded discounts are applied. This field should be used in locales, such as the United States, that typically show the base price without taxes and fees on search results. - The
inclusive_strikethroughfield presents the total price, before discounts, with taxes and fees included. This field is designed to allow you to more clearly display the discount that applies in locales that present all inclusive pricing, i.e. base, taxes, and fees. The field returns a value in both the billable and requested currencies.
Example
[
{
"property_id": "19248",
"rooms": [
{
"id": "123abc",
"room_name": "Fancy Queen Room",
"rates": [
{
"id": "333abc",
...
"occupancy_pricing": {
"2": {
"nightly": [ ... ],
"stay": [ ... ],
"totals": {
"inclusive": { ... },
"exclusive": { ... },
"inclusive_strikethrough": {
"billable_currency": {
"value": "726.63",
"currency": "CAD"
},
"request_currency": {
"value": "549.60",
"currency": "USD"
}
},
"strikethrough": {
"billable_currency": {
"value": "650.00",
"currency": "CAD"
},
"request_currency": {
"value": "491.64",
"currency": "USD"
}
},
"marketing_fee": { ... },
"gross_profit": { ... },
"minimum_selling_price": { ... },
"property_fees": { ... }
},
"fees": { ... }
}
}
}
]
}
]
}
]Promotion and discount price display
When displaying a discount saving amount based off a promotion or strikethrough provided in the Availability and Price Check APIs, certain points of sale require details to be provided about the Standard Rate Price (i.e. the price the discount is calculated from). Please refer to the statements below on what terminology to use.
EU: Provide clear details about the standard rate price, e.g. "This price is the standard rate provided by the property based on your search."
Italy: Use the following wording: "Questo prezzo è basato sulla tariffa generalmente applicabile fornita dalla struttura per questa camera e per queste date".
Refundability options
The current_refundability field enables partners to display all refundability options, offering travelers rate transparency and enhanced flexibility.
The three options are:
refundablenon_refundablepartially_refundable
What does partially refundable mean?
Partially refundable refers to rates where:
- The cancellation penalty is more than 0 but less than the total value of the booking.
and/or
- There are non-refundable date ranges within the stay period.
How is leveraging the current_refundability field better than using the refundable Boolean flag alone?
The refundable Boolean flag indicates if a rate is fully refundable or not but it returns a false result for partially refundable rates, which is misleading for travelers. The current_refundability field offers a more nuanced option which provides more accuate information on the refundabilty of rates.
How can partners receive the current_refundability field within the Shop response?
Partners need to request the current_refundability field under the include parameter in the Shop request.
Example
"property_id": "23060",
"status": "available".
"rates": [
{
"id": "201392692",
"status": "available",
...
...
...
...
"current_refundability": partially_refundable,
"cancel_penalties":[
{
"start": "2024-10-08T23:59:00.000+02:00",
"end": "2024-10-09T23:59:00.000+02:00",
"nights":"1",
"currency": "EUR"
}
]
}
]Unavailable reason
The unavailable_reason feature allows you to request actionable information on why a property is fully unavailable for a set stay (stay dates and occupancies). The optional request parameter include=unavailable_reason must be included when shopping to receive this information in the response. However, not every unavailable property will have an actionable reason for not being bookable. Those properties will not be returned in the response.
The Shop response can include a mixture of available and unavailable properties. The unavailable properties will include a property_id, score, and an unavailable_reason section that includes a code with a short explanation for the property being unavailable (given in English) and data for additional information that could be adjusted in the request to make the property/rooms/rate plans available. For example, if an unavailable_reason code was adults_exceed_threshold the 2 in data would mean 2 adults is the maximum number allowed for that room/rate and any occupancy greater than 2 would return an error.
Note: Multiple restrictions can apply for a property but only one unavailable_reason will be returned.
Example
[
{
"property_id": "824739",
"score": 12345,
"unavailable_reason": {
"code": "adults_exceed_threshold",
"data": "2"
}
}
]See here for full list of codes returned.
Amenity filters
Optionally, you can filter properties returned in the Rapid Shop response using the amenity_category request parameter along with one or more specific amenities.
See the amenity categories section of the Content reference lists here for a list of amenities that can be used to filter the response.
Examples
Single amenity filter:
&amenity_category=free_breakfastMultiple amenity filter:
&amenity_category=free_breakfast&amenity_category=free_airport_transfer&amenity_category=casinoRate limiting
Traffic optimization is achieved by applying rate limits to partners. These rate limits ensure the continued delivery of a stable and maintainable service to partners while also guaranteeing the efficient use of Expedia Group systems. For Shop traffic, the significant factors for determining load are the number of properties, the number of rooms, and length of stays being searched in each request.
For more information on rate limiting, see here.
Price Check
Confirms the price returned by the Shop response. Use this API to verify a previously-selected rate is still valid before booking. If the price is matched, the response returns a link to request a booking. If the price has changed, the response returns new price details and a booking link for the new price. If the rate is no longer available, the response will return a new Shop request link to search again for different rates.
There may be a slight variation of approximately 0.1% (per room × person × night) in the billable amount displayed on PriceCheck for totals.property_fees and fees compared to the previous Shop response, which could include an amount adjusting to zero. The discrepancy in fees due at the property arises when the request_currency and billable_currency differ for Expedia Collect rates. API function will not be impacted by this discrepancy.
Hold and Resume
Some inventory hasn’t been released to hold and resume partners. You can now access these incremental rates by adopting the new shopping indicator of non-holdable rates. More detail can be found here.
Payment Options
Returns the accepted payment options where Expedia is taking payment from the end traveler (EPS MOR). Use this API to power your checkout page and display valid forms of payment, ensuring a smooth booking.
Important notes
languageonly uses hyphenated pairs of two-digit language and country codes. Review our supported languages before integrating any codes.- The two-digit
countrycodes set the traveler's point of sale, they do not affect localized content. - No static data (names, star ratings, geography information, etc.) is returned. Only availability and rate-related data is provided.
- Tokenized request links will expire after a short period. If a token link returns an HTTP 503 error, the link has likely expired. Obtain a new price check or deposit link from a fresh Shop response and attempt again. Do not store link values for long term re-use.
- Rapid API allows properties to update their content at any time. We require your best effort to provide the most up-to-date information to customers. The Shop API provides the most current information for available rooms and rates. To obtain additional property-level, room-level, and rate-level information not returned in this response, use our Property Content API.
- APIs provide prices based on one room only, multiple room bookings require an additional calculation by yourself. As a part of launch requirements, your integration should display the detailed price breakdown to end users at certain steps in the booking journey. The breakdown can be found behind this secured documentation link.
To perform test requests against this service, see our test request documentation.
Variable taxes and fees
There may be mandatory taxes and fees that are not included in the total price because they cannot be calculated at the time of booking, for example charges that vary based on in-stay activity or variable accomodation taxes in some markets, such as Japan and Colombia. Information about how these variable taxes and fees are calculated will be available in the Content API. This information should be displayed prominently to travelers.
API details
Explore the shopping-related endpoint definitions on this page, then use the API Explorer or another testing software to get an understanding of how the examples and schema definitions compare to the actual output.
Additional resources
Whether you're looking to try out all the Rapid API endpoints or to download its OpenAPI specs or our Postman collection, we have you covered.