Merchandising API Users Guide
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.
Merchandising Service Overview
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:
- Most watched items—items that are currently the most watched
- Great deals—items that are currently on-sale or offering free shipping
- Related category items—items from categories that are related to a specific item or category
- Top-selling products—products with the highest purchase rates
Refer to the eBay Merchandising API API 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
Merchandising Use Cases
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.
Improved Buying Experience
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.
Capture Impulse Sales
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.
Optimize Your Selling Strategy
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.
Increase Affiliate Commission Revenue
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 API Reference for information about how to specify your affiliate details when you make API calls.
Combining with Other eBay APIs
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
eBay Shopping API offer access to public read-only data such as searching for items, products, and eBay member profiles.
eBay Trading API
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.
Additional eBay APIs
See the Products page to learn more about eBay API products and upcoming product releases and feature enhancements.
Back to top
Working with the Merchandising API
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:
- Service Endpoints—the Merchandising API has unique gateway URLs (service endpoints) for Production and Sandbox:
- Production endpoint:
- Sandbox endpoint:
- HTTP headers and URL parameters—the Merchandising API uses a Service Oriented Architecture (SOA) framework, which requires a new set of HTTP headers and URL parameters. For example, although you can use the same AppID you use with the Shopping or Trading APIs, the header (
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.
- Schema and data type changes—the Merchandising API does not share schema or data types with other eBay APIs. In the API, you will find the following differences from other eBay APIs:
- New types, such as Item, with standard content like item ID, title, pricing information, time left, and a View Item page URL. Although the types and fields are slightly different, the eBay data is the same.
- Completely new types, such as the ErrorMessage type, a completely new structure for error information
- No site ID! Instead, we provide globalId, a unique identifier for a combination of site, language, and territory. See the Global ID Values table for a list of global IDs that map to site IDs. The global ID you use must map to an eBay site with a site ID.
- Naming conventions—the naming conventions for the Merchandising API are slightly different. Most notably, call names and fields in the Merchandising API begin with lowercase letters.
- Versioning strategy—the version numbering scheme for the Merchandising API is different from the scheme used by the eBay Shopping and Trading APIs. The Merchandising API version consists of three digits (e.g., 1.2.3):
- The first digit indicates the major release version. Major releases are not backward compatible.
- The second digit indicates the minor release version. Minor releases consist of feature additions or behavior changes that are backward compatible.
- The third digit indicates the maintenance release version. Maintenance releases are for correcting small problems have have minimal impact on the features or function of the Merchandising API.
See Making a Merchandising API Call for information about how to construct a Merchandising API call. Refer to the API Reference for details about the API structure and logic.
API Call Limits
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:
- Go to http://developer.ebay.com/ and click the Join button.
- Fill out the Join form.
- Generate your Production keys.
- Use your Production AppID for making calls in Production (the eBay website).
Supported Request and Response Formats
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 API Reference for a list of calls in the Merchandising API. The Call Reference includes the following information:
- Prototypes of the request and response structure for each call
- Comprehensive list of inputs and outputs supported by each call and descriptions of their meaning and behavior
- Call samples (request and response)
- Index of schema elements (types, fields, enumerations)
- Change history information for each call
Make a Call
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:
The response will be in XML format.
To make the call:
- Sign up and get an AppID.
- Enter your AppID and click the Make Call button to get a list of the top-selling products on eBay.
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
Copyright © 2008–2014 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.