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 the upcoming changes, owing to the California Price Display Regulation (Berman Law) that is effective from 2024-07-01.

What is the law?

The law prohibits advertising, displaying, or offering a room rate that does not include all fees or charges required to stay at a short-term lodging except taxes and fees imposed by a government on the stay. The bill also requires a place of short-term lodging to include in the total price to be paid, before the consumer reserves a stay, all taxes and fees imposed by a government on the stay. “Short-term lodging” means any hotel, motel, bed and breakfast inn or other transient lodging, and includes short-term rentals or a residential property that is rented to a visitor for 30 consecutive days or less. For more information, please see California Assembly Bill 537.

Expedia Group is making 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 upcoming changes?

Expedia is enhancing 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 will also be available in a new field property_inclusive_strikethrough. In addition to the new property inclusive display fields, we are realigning the way that taxes and fees are broken out in the API response. All Expedia collected fees will be part of the nightly and stay property_fee price breakout type, and all Expedia collected taxes will be part of the nightly and stay tax_and_service_fee price breakout type.

As this will be a global change implemented to all properties, the release date has been rescheduled to 2024-05-29 to ensure smooth adoption and understanding of the changes. 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. You 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\
&currency=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=business

Strikethrough pricing

• The strikethrough field 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_strikethrough field 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".

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_breakfast

Multiple amenity filter:

&amenity_category=free_breakfast&amenity_category=free_airport_transfer&amenity_category=casino

Rate 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. This potential discrepancy in due at property fees may arise only when the request_currency and billable_currency differ for Expedia Collect rates. API will function without any errors in this circumstance.

Payment Options

Returns the accepted payment options. Use this API to power your check-out page and display valid forms of payment, ensuring a smooth booking. Rates offered as property collect will return card types accepted by the property. All other rate types will return Expedia's accepted payment options.

Important notes

• language only uses hyphenated pairs of two-digit language and country codes. Review our supported languages before integrating any codes.
• The two-digit country codes 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.

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.

Go to the API Explorer