Overview

Take advantage of the new Merchandising API to identify deals more easily and benefit from machine learning-powered recommendations

The Merchandising API delivers direct access to Expedia-sourced property discounts, their associated campaigns and assets, and personalized deal, destination, and property rankings powered by machine learning. Use the Merchandising API to populate traveler- or agent-facing marketing experiences such as promotional emails, app widgets, website banners, and carousel experiences — and execute a winning year-long merchandising strategy.

You also have access to a Marketing section in your Partner Portal account where you can browse upcoming campaigns, export customized deal lists, select campaign copy and imagery to use, and track travel trends and campaign performance. If you aren’t seeing the Marketing section in your Portal, submit a support ticket.

Campaign content endpoint

The campaign content endpoint delivers upcoming campaign details including campaign ID, booking and stay start and end dates, and number of properties participating. You gain direct access to Expedia-curated campaign assets such as campaign thematic images, destination imagery, and suggested copy to create traveler-facing or agent-facing merchandising experiences including promotional emails, app widgets, and website banners. Additionally, you receive information about limited time offer (LTO) campaigns with a booking window within the next six months as well as evergreen campaigns available throughout the year.

You can use the Campaign Content endpoint to search upcoming campaigns using request parameters including:

• Bookable date range
• Stay date range
• At or above values for minimum discount
• LTO versus evergreen offers

For LTO campaigns with a booking window beyond six months, the following fields will be excluded:

• Booking and travel dates
• Min and max discount %

Other details

You can use the property_count field in the Campaign Content response to determine the most up-to-date number of properties providing deals within a campaign. We recommend you check the property_count close to the campaign booking start date since property participation in merchandising campaigns is dynamic and participation from properties tends to be most complete and reliable as the campaign launch approaches.

You can use the min_discount and max_discount fields in the Campaign Content response to determine the minimum and maximum percentage discount available within that campaign. For example, if the deepest discount offered by a property in that campaign is 60% off, the max_discount value in the API response would be 60%, whereas, if the lowest discount offered by a property in that campaign is 4%, the min_discount field would be 4%.

Promotions endpoint

You can easily search and filter the Promotions response for more targeted deals, so you have full control over what deals you surface to travelers. You can also curate these deals to build your own campaign themes instead of using Expedia-defined campaigns and associated assets.

With the Promotions endpoint you can:

• Deliver deals and discounts associated with a specific campaign
• Search and filter deals with the help of multiple request parameters, including the ability to request deals for a specific campaign or across multiple campaigns
• Surface the most up-to-date, appealing property deals to build a high-converting campaign

Search and filter

You can use the Promotions endpoint to easily filter and search for deals using request parameters such as:

• Campaign ID and/or property ID
• Bookable date range
• Stay date range
• At or above values for minimum review score, minimum star rating, and/or minimum discount
• Limited time vs evergreen distinction
• Member-only and mobile-only deal flags
• Super region or specific destinations
• Machine learning relevancy ranking sort order

Response details

The below details will be returned in the Promotions API response:

• Promotion ID, corresponding campaign ID, and property ID
• Bookable date range, stay date range, blackout dates, and advance purchase window
• Limited time vs. evergreen distinction
• Machine learning-powered relevancy rankings unique to your business for the deals, properties, and destinations returned in the response
• Specific destinations and chain ID information
• Tokenized link to the existing Rapid Property Content API to pull property-level imagery to feature in your merchandising experiences
• Tokenized Shopping link to conduct deal-specific merchandising Shopping API call to receive live pricing and availablity

Other details

• If you want to search deals for a set booking window you can pass values for both bookable_start and bookable_end date. For example, by passing 2027-10-15 (October 15, 2027) in the bookable_start field and passing 2027-10-30 (October 30, 2027) in the bookable_end field, you will receive all deals that are bookable between October 15th and October 30th inclusive. However, if you who want to see a larger set of deals you can use either bookable_start or bookable_end date. For example:
  • By passing 2027-10-15 (October 15, 2027) in the bookable_start field, you will receive all deals that are bookable on and after October 15th. This will provide a larger set of deals.
  • By only passing 2027-10-30 (October 30, 2027) in the bookable_end field, you will receive all deals that are bookable on and before October 30th. Again, this will provide a larger set of deals.
• Deals go live (i.e. become available to book) according to the property's time zone. So, if a deal starts on 21st March for a property in Sydney, Australia, the deal will become live for booking at 12:01am Sydney time for all partners in the world.
• You can use the include request parameter on the Promotions endpoint to customize the size of the response you receive. So instead of receiving all response fields, if you only need a few fields returned, you can add those specific field names in the include parameter.
• You can start making requests to the promotions API in advance but should also request as close to the campaign bookable start date as possible for the most accurate and up-to date representation of the deals from properties. We suggest approximately two weeks before the campaign starts. This is because participation from properties tends to be most complete and reliable as the campaign launch approaches.
  • We also suggest you request promotions a few days after the campaign starts such that you always get the refreshed latest deals list. Additionally, we suggest you request the promotions API daily to get a refreshed and latest list of deals provided by properties.
• If you’re interested in building destination-based merchandising campaigns, you can make a region-specific Promotions API request using the relevant region_id from the Rapid Geography API. The only region type accepted by the promotions endpoint is city. Other region types such as multi_city_vicinity, point_of_interest, neighbourhood, etc. will return a blank response.

Linking Promotions API and Shop Availability API

You can use the shop link token in the Promotions API response to call our regular Availability API and receive real-time pricing and availability. The token contains essential details about deals and property data and is unique for every deal.

Example Promotions response

[
  {
    "promotion_id": "123456",
    "campaign_id": "12345",
    "property_id": "123456",
    ...
    "links": {
      "content": {
        "method": "GET",
        "href": "/v3/properties/content?property_id=123456&language=en-US&supply_source=expedia"
      },
      "shop": {
        "method": "GET",
        "href": "/v3/properties/availability?token=XFleAkNUU1YKACg5HcAtdVw8SQVUPUApTAF0CAApdBg==",
        "required_parameters": [
          "checkin",
          "checkout",
          "currency",
          "country_code",
          "occupancy",
          "rate_plan_count",
          "sales_channel",
          "sales_environment"
        ]
      }
    }
  }
]

When you choose a deal to promote, simply use the shop link token to make an Availability API call with the required parameters. The Availability API response will then show all the regular details about the deal you have chosen which will enable you to make a focused deal-specific Shopping API call in an automated fashion. Along with this token, you have the flexibility to further shop for other properties in the same Shopping API request (regular limit of total 250 properties in one Shopping call still applies) further expanding your Shopping search.

Example Shop request using the token

curl -X GET "https://test.ean.com/v3/properties/availability\
?token=XFleAkNUU1YKACg5HcAtdVw8SQVUPUApTAF0CAApdBg==\
&checkin=2026-06-01\
&checkout=2026-06-03\
&currency=USD\
&country_code=US\
&occupancy=2\
&rate_plan_count=1\
&sales_channel=website\
&sales_environment=hotel_only" \
 -H "accept: application/json"\
 -H "accept-encoding: gzip"\
 -H "authorization: EAN apikey=abcd1234,signature=090a77e7ddd7779980231,timestamp=1697664047"\
 -H "user-agent: TravelNow/3.30.112"

When making multiple Availability API requests, we ask that you use the shop link token for every single call. Every time you make a Promotions API request, a new token is generated for each of the shop links. This is because every token is unique and can be tracked to a specific Promotions API call. So, if you are doing a daily refresh of the Promotions data, it is important that you use the latest generated token.

The shop link token from the Promotions API response enables our team to better understand your end-to-end Merchandising API journey which in turn will help us provide better performance reporting (on Marketing section) and enhance our machine learning recommendations.

Further, use the new deal filter available in the Rapid Shopping Availability endpoint to only receive rates that feature active promotions. This gives you the flexibility to create a Shopping request with an exclusively merchandising focus and ensure that the all the rates returned have a deal attribute.

Example response

"promotions": {
. "deal": {
.   "id": "999abc",
.   "description": "Book early and save 15%"
. }
}

Note: The id and description available in the Merchandising API response are different to those returned in the Shopping API response. We strongly advise that you use the id and description returned by the Merchandising API.

Machine learning recommendations

The machine learning-powered relevancy rankings delivered in the Promotions response are unique to each partner, so the rankings you receive will differ from what anyone else receives. You can use the machine learning recommendations to identify the best deals, properties, and destinations to promote in your merchandising campaigns. Higher-scoring deals, properties, and destinations may have a higher likelihood of driving conversion among your unique traveler base.

• Currently, you will receive relevancy rankings for the top 10k deals in each campaign. In our testing, we found the value and impact of this rank became negligible beyond the first 10k deals.
• Based on your use case, you can use the sort_by parameter to define the sort order of the Promotions response, choosing to order based on deal, property, or destination relevancy as determined by our machine learning model for you to get the maximum value from merchandising in terms of visibility and bookings from the travelers.
  • If you pass sort_by = promotion you will receive all the deal results ranked high-to-low (1 to 10,000) per our proprietary machine learning algorithm. You can use this sort to get the top recommended deals that our model expects to convert more.
  • If you pass sort_by = property you will receive all the deal results from the properties ranked high-to-low per our proprietary machine learning algorithm.
  • If you pass sort_by = destination you will receive all the deal results from the destinations ranked high-to-low per our proprietary machine learning algorithm.

Note: Machine learning recommendations are also available in the Marketing section in Portal. Please reach out to your account manager for more details.

Launch requirements

Compliance responsibility

You are solely responsible for ensuring compliance with all applicable legal and marketing guidelines when running campaigns.

Content integrity

Expedia-provided images must not be modified. You may use your own creative assets if preferred; however, you are solely responsible for ensuring compliance with all applicable copyright and intellectual property laws.

API details

Explore the merchandising-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