Merchandising API
You can find links to the Merchandising API documentation in the top navigation bar. Information about the schema location is in the Schema Location section of the "Making an API Call" topic.
Are you just getting started with the Merchandising API? The following pages contain information that describes how to join the eBay Developers Program:
| Version | Release Date | |
|---|---|---|
| 1.5.0 | 2011-8-20 and Jan. 2015 | |
| 1.4.0 | 2010-3-3 | |
| 1.2.0 | 2009-8-19 | |
| 1.1.0 | 2008-8-12 | |
| 1.0.0 | 2008-6-11 |
Index of Changed Calls - 1.5.0
Documentation Changes and Errata - 1.5.0
For a current list of known issues, see Site Status and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
| Name | Part of Schema | Type of Change |
|---|---|---|
itemFilter |
Complex type | Disabled (2015) |
subTitle |
Field | Disabled (2015) |
DiscountPriceInfo |
Complex type | New |
PriceTreatmentEnum |
Enumerated type | New |
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1.5.0.
Sellers can specify discount pricing values for an item to give the item either a Strike-Through Pricing (STP) or Minimum Advertised Price (MAP) display treatment. This feature is available to qualified sellers (and their associated developers) who participate in the Discount Pricing program. Once qualified, sellers can apply Discount Pricing to both MSKU and Non-MSKU items. STP is available on the US, UK, and DE sites while MAP is available only on the US site. For more information, see: Displaying Discount Pricing Information to Buyers.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
None for this release.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1.5.0 and Changed Functionality - 1.5.0.
Due to an eBay platform change in January 2015, the following changes occurred.
Index of Changed Calls - 1.4.0
Documentation Changes and Errata - 1.4.0
For a current list of known issues, see Site Status and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
| Name | Part of Schema | Type of Change |
|---|---|---|
ItemFilter |
Complex type | New |
ItemFilterType |
Enumerated type | New |
Affiliate.delimiter |
Element | New |
GetRelatedCategoryItemsRequest.itemFilter |
Element | New |
GetSimilarItemsRequest.itemFilter |
Element | New |
Item.delimiter |
Element | New |
Product.delimiter |
Element | New |
See the Site Status for bug fixes related to this release.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1.4.0.
The getMostWatchedItems, getRelatedCategoryItems, and getSimilarItems calls can now return as many as 50 item recommendations. The maximum number of item recommendations is specified with the maxResults input field. Previously, these calls were limited to a maximum of 20 item recommendations. The default number of results is still 20.
The getRelatedCategoryItems and getSimilarItems calls can now be filtered to restrict recommended items to only items available on worldofgood.ebay.com by eBay. Results can be further restricted by specifying the World of Good category in the filter.
The name and value fields in the following filter snippet restrict the item recommendations to only items available on worldofgood.ebay.com. The paramName and paramValue fields further restrict results to items listed in category 40 (Accessories) on worldofgood.ebay.com.
... &itemFilter.name=WorldOfGoodOnly &itemFilter.value=true &itemFilter.paramName=WOGCategory &itemFilter.paramValue=40 ...
| Note: To locate a specific World of Good category, go to the worldofgood.ebay.com home page. Top-level categories are listed under Shop by Category on the left-hand side of the page. Click the category you want to use to restrict your search results. The resultant URL contains the category ID as a numeric value, appearing before "/list" at the end of the URL (e.g., http://worldofgood.ebay.com/Belts-Hats-Scarves-Shawls/40/list). If a category has children categories, they will be displayed under the Category on the left-hand side of the page. The numeric category ID can be determined from the URL for child categories in the same fashion. |
The getVersion call was added with this release. This simple call can be used to monitor the service for availability. This call has no input parameters and the response contains only the standard output fields.
The xs:any wildcard in existing complex types in the WSDL has been replaced by an optional sequence containing a delimiter element and an xs:any wildcard. This makes the schema structure deterministic, in accordance with XML rules and standards, which improves the compatibility of the WSDL with development tools.
The delimiter elements are purely for structural framing within complex types. If you pass the delimiter field in a request, any data it contains will be ignored. If they are returned in a response, they will be empty. This schema change will not affect existing applications. Because the nested sequence is optional, the delimiter fields are optional, as well.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
As of January 15, 2010, eBay evaluates the CONTENT-TYPE header against the request payload format. If the CONTENT-TYPE value is incorrect for the payload, the request will fail. Previously, eBay did not validate the CONTENT-TYPE header in requests.
See Making An API Call for more information, including standard values for supported request formats.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1.4.0 and Changed Functionality - 1.4.0.
None for this release.
Index of Changed Calls - 1.2.0
Documentation Changes and Errata - 1.2.0
For a current list of known issues, see the Site Status and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
No changed calls in this release.
No schema changes in this release.
See the Site Status for bug fixes related to this release.
Message part names in the WSDL have been renamed from "parameters" to "params" to correct a problem for .NET developers. This fix allows .NET users to add web references in Visual Studio without errors.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
None for this release.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1.2.0.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
None for this release.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1.1.0 and Changed Functionality - 1.1.0.
The documentation has been updated to indicate that getMostWatchedItems returns auction items only when they have one or more bids.
The description for the trackingId field has been updated to indicate the correct size of Campaign IDs, 10 digits.
Index of Changed Calls - 1.1.0
Documentation Changes and Errata - 1.1.0
For a current list of known issues, see the Site Status and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
Schema changes in pink (for example, SomeType.Somedata) are for future use. Monitor upcoming release notes for descriptions of their purpose and use.
| Name | Part of Schema | Type of Change |
|---|---|---|
GetSimilarItemsRequest |
Complex type | New |
BaseServiceResponse.timestamp |
Element | New |
BaseServiceResponse.version |
Element | New |
The getDeals call is not returning any item recommendations.
The getMostWatchedItems call does not work properly for EBAY-FRCA (eBay Canada, French).
The getTopSellingProducts call does not work for the following global IDs (eBay sites): EBAY-FRBE (eBay Belgium, French), EBAY-NLBE (eBay Belgium, Dutch), or EBAY-AU (eBay Australia).
In some cases, the item recommendations returned by getRelatedCategoryItems are not closely related to the item specified in the request.
See the Site Status for bug fixes related to this release.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
The new getSimilarItems call allows you to retrieve a list of recommended items that are similar to the specified item. This call can be used to recommend items to buyers who have lost items they were bidding on, or to recommend items as alternatives for watched items that have ended.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1.1.0.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
The response for each Merchandising call now includes the following fields:
In the initial release of the Merchandising API, calls returned data for the eBay US site only. Calls are for the eBay US site by default, but the GLOBAL-ID URL parameter (or X-EBAY-SOA-GLOBAL-ID HTTP Header) can be used to get results from other eBay sites. In Version 1.1.0, the global ID can be specified (e.g., GLOBAL-ID-EBAY-GB) to retrieve data from international eBay sites.
Refer to Global ID Values for a list of global IDs and eBay Site ID to Global ID Mapping to see the list sorted by the corresponding site ID.
Note: At the time of release, some calls do not work with all global IDs. For example, getTopSellingProducts does not work for the following global IDs (eBay sites): EBAY-FRBE (eBay Belgium, French), EBAY-NLBE (eBay Belgium, Dutch), or EBAY-AU (eBay Australia). getMostWatchedItems does not work for EBAY-FRCA (eBay Canada, French).
The product reference ID returned by getTopSellingProducts call in the initial release of the Merchandising API was in the long format referred to as the ProductMementoString parameter. The long format has limited application. In Version 1.1.0, getTopSellingProducts returns the shorter product reference ID, which can be used to search for products, listings, and reviews in the Shopping API. Refer to FindItemsAdvanced, FindProducts, and FindReviewsAndGuides pages in the Shopping API Call Reference for information on using the product reference ID for searches.
Long product reference ID returned by getTopSellingProducts in version 1.0.0:
<productRecommendations>
<product>
<productId type="Reference">
98398:2:1051:4055955490:143584350:f7ddef8d65bb5c3fc858bcf11ed7bc4e:1:1:1:1375474706
</productId>
<title>Grand Theft Auto IV (Playstation 3)</title>
...
Short product reference ID returned by getTopSellingProducts in version 1.1.0:
<productRecommendations>
<product>
<productId type="Reference">53683360</productId>
<title>Grand Theft Auto IV (Playstation 3)</title>
...
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1.1.0 and Changed Functionality - 1.1.0.
The getDeals call is not returning data. Until this problem is corrected, getDeals has been removed from the Call Reference. The getDeals schema remains in the WSDL.
This is the first release of the eBay Merchandising API.
For a current list of known issues, see Site Status and the Knowledge Base.
These calls are included in the initial release of the eBay Merchandising API.
Copyright © 2008–2016 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.