The Merchandising API provides item and product recommendations that can be used to cross-sell and up-sell eBay items to buyers. This document gives an overview of the Merchandising API, explains what the API is for, describes how to use it, and points you to other resources where you can learn more. The Merchandising API can be used independently from other eBay APIs, but can be used together with other eBay APIs to create rich applications.
The eBay Merchandising API retrieves valuable information about products or item listings on eBay to help you sell more merchandise to eBay buyers. Buying applications can provide suggested products or item listings based on buyers' searching or selection activity. Sellers can augment their own listings with cross-promotions to create a better shopping experience, which can help attract and retain buyers.
The Merchandising API consists of calls that return item or product recommendations based on simple inputs, such as a query, an item ID, or a category ID. The API returns the following types of merchandise recommendations:
Refer to the eBay Merchandising API Call Reference for a list of API calls and the associated inputs and outputs for each.
|Note: If you are familiar with the eBay Shopping API or the eBay Trading API, you may notice some differences in the API conventions and the way requests are routed for the Merchandising API. The cause for these differences is that the Merchandising API is built on eBay's Services Oriented Architecture (SOA) framework. For more information, see What's Different in this document.|
Back to top
The eBay Merchandising API can be used with other eBay APIs to improve buying applications. The merchandising information returned by the service can also help sellers better manage their inventory.
On its own, the Merchandising API does not provide enough search and selection capabilities to build a complete shopping, buying, or selling application. However, the merchandising data can be combined with information from other eBay APIs to create a better shopping and buying experience.
Standard finding results can be enhanced with related items. Related item recommendations can provide cross-sell or up-sell opportunities. The getRelatedCategoryItems call displays items related to a specified category or item ID.
|Note: The getDeals call is not returning any item recommendations in the current release of the Merchandising API. There is no ETA available for when this problem will be resolved.|
Show buyers where the best deals are based on their shopping decisions. The getDeals call retrieves items that have free shipping or items that are on a promotional sale. The eBay Deal Finder page (shown below) illustrates one way you can help buyers browse for bargains on eBay.
Add interest and excitement for buyers by showing them what other people are watching and buying on eBay. The getMostWatchedItems and getTopSellingProducts do just that. The Shopping API includes FindPopularItems and FindPopularSearches calls, which can also be used to show buyers popular eBay items.
All these approaches help connect buyers with products and listings.
The Merchandising API provides data that can help sellers make the most of their inventory. Data about eBay buying habits, such as top-selling products or most watched items, can inform seller decisions about inventory and pricing. The getTopSellingProducts call not only retrieves a list of the top-selling products, but provides the price range in which they are offered. The getMostWatchedItems call provides the current price for the most watched items, which might help sellers optimize their own pricing tactics. If buyers aren't finding what they are looking for in a seller's inventory, the seller can use getDeals or getRelatedCategoryItems to supplement their inventory with related items to ensure buyers have a good experience.
Note: The Merchandising API provides dynamic merchandising data for active listings. For behavioral trends or historical data, you should consider using the Research API for eBay (powered by DataUnison) or the eBay Market Data Program.
If you use affiliate parameters, you can get commissions based on transactions and based on registrations of new users. Affiliate parameters enable the tracking of user activity and can be used with all Merchandising API calls.
See the eBay Partner Network for information about commissions.
Refer to the Call Reference for information about how to specify your affiliate details when you make API calls.
The Merchandising API can be used in conjunction with any of the eBay APIs. We recommend you try using the Merchandising API together with one or more of the following APIs.
eBay Shopping API offer access to public read-only data such as searching for items, products, and eBay member profiles.
eBay Trading API offer authenticated access to private eBay data to enable automation and innovation in the areas of listing items, retrieving seller sales status, managing post-transaction fulfillment, and accessing private user information such as My eBay and Feedback details.
See the Products page to learn more about eBay Web Services products and upcoming product releases and feature enhancements.
Back to top
The Merchandising API is simple and easy to use. This section outlines the fundamentals of how to use the Merchandising API.
The eBay Merchandising API works similarly to other eBay APIs. For example, the Merchandising API uses the same authentication as the Shopping API. In fact, you can use the same AppID. However, the Merchandising API is built on eBay's Services Oriented Architecture (SOA) framework, and as a result, there are some changes to the API conventions and how you route requests.
Here are the most notable differences:
EBAY-SOA-CONSUMER-ID) or URL parameter (
CONSUMER-ID) you use is different. See Standard URL HTTP Header Values in Making a Merchandising API Call for more information.
See Making a Merchandising API Call for information about how to construct a Merchandising API call. Refer to the Call Reference for details about the API structure and logic.
Please refer to the API Call Limits page on the eBay Developers Program site for current default call limits and call limits for applications that have completed the Compatible Application Check, which is a free service that the eBay Developers Program provides to its members.
All that is required to use the Merchandising API is an AppID. If you already have an AppID for use with another eBay API, it will work for Merchandising API, as well. You must specify your AppID in the
EBAY-SOA-CONSUMER-ID header (or
CONSUMER-ID URL parameter) of every request.
To get your AppID:
The eBay Merchandising API supports HTTP POST and HTTP GET methods. The HTTP POST method supports SOAP or XML formats in the request and name-value (NV), SOAP, or XML formats in the or response. The HTTP GET method supports NV format for requests and NV, SOAP, or XML formats in the response.
For details about making calls using supported methods and formats, see Making a Merchandising API Call.
Refer to the Call Reference for a list of calls in the Merchandising API. The Call Reference includes the following information:
The eBay Merchandising API is easy to use. All you need is your AppID. In the following steps, you will make a getTopSellingProducts call. The request uses the HTTP GET method and looks like this:
http://svcs.ebay.com/MerchandisingService? OPERATION-NAME=getTopSellingProduct &SERVICE-NAME=MerchandisingService &SERVICE-VERSION=1.0.0 &CONSUMER-ID=YourAppID
The response will be in XML format.
To make the call:
The Merchandising API is optimized to retrieve information from the live eBay site and you can safely test your application with calls to the live eBay site, but the Sandbox supports the Merchandising API, as well.
For more information about testing, refer to Testing Overview in the Making a Merchandising API Call document.
Back to top
You can get more information about the eBay Merchandising API at these locations:
Back to top
© 2008–2011 eBay Inc. All rights reserved.
This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.