Merchandising API Release Notes
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:
- Merchandising Users Guide—an introduction to the eBay Merchandising API
- eBay Developer Documentation Center
- eBay API - Quick Start
| 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 |
Version 1.5.0
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.
Index of Changed Calls - 1.5.0
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.
New Calls
No new calls in this release.
Changed Calls
Schema Changes - 1.5.0
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 |
Announcements - 1.5.0
New Features - 1.5.0
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.
Discount Pricing Information Enables You To Create Special Price Display Treatments
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.
Changed Functionality - 1.5.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.
Documentation Changes and Errata - 1.5.0
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.
Changes in 2015
Due to an eBay platform change in January 2015, the following changes occurred.
- The country code IN (India) is no longer supported for the getSimilarItems call.
- The subTitle field is longer supported for the getSimilarItems and getMostWatchedItems calls. This field is returned in the response but will always be blank.
- The itemFilter type, which lets you restrict results to only items available in the World of Good marketplace, is no longer supported for the getSimilarItems and getRelatedCategoryItems calls.
- In the past, the getMostWatchedItems response returned only auction items that had one or more bids. Now auction items with and without bids are returned.
Version 1.4.0
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.
Index of Changed Calls - 1.4.0
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.
New Calls
Changed Calls
Schema Changes - 1.4.0
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 |
Announcements - 1.4.0
Change Requests
See the Site Status for bug fixes related to this release.
New Features - 1.4.0
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.
Increased Maximum Number of Results
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.
World of Good Filter
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. |
New getVersion Call
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.
Schema Changes to Support UPA Constraints
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.
Changed Functionality - 1.4.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.
Optional CONTENT-TYPE Header Must Have Correct Value
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.
Documentation Changes and Errata - 1.4.0
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.
Version 1.2.0
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.
Index of Changed Calls - 1.2.0
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.
New Calls
No new calls in this release.
Changed Calls
No changed calls in this release.
Schema Changes - 1.2.0
No schema changes in this release.
Announcements - 1.2.0
See the Site Status for bug fixes related to this release.
Changes to Message Part Names
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.
New Features - 1.1.0
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.
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.
Documentation Changes and Errata - 1.2.0
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.
getMostWatchedItems Constraint for Auctions
The documentation has been updated to indicate that getMostWatchedItems returns auction items only when they have one or more bids.
Affiliate Tracking ID is 10-digit Number
The description for the trackingId field has been updated to indicate the correct size of Campaign IDs, 10 digits.
Version 1.1.0
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.
Index of Changed Calls - 1.0.0
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.
New Calls
Changed Calls
Schema Changes - 1.1.0
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 |
Announcements - 1.1.0
getDeals Not Working
The getDeals call is not returning any item recommendations.
getMostWatchedItems Not Working for Some eBay Sites
The getMostWatchedItems call does not work properly for EBAY-FRCA (eBay Canada, French).
getTopSellingProducts Not Working for Some eBay Sites
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).
getRelatedCategoryItems Returns Irrelevant Item Recommendations
In some cases, the item recommendations returned by getRelatedCategoryItems are not closely related to the item specified in the request.
Change Requests
See the Site Status for bug fixes related to this release.
New Features - 1.1.0
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.
Retrieve Similar Items
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.
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.
More Information in Call Responses
The response for each Merchandising call now includes the following fields:
- timestamp—the date and time when eBay processed the request.
- version—the version of the schema eBay used to process the request (e.g., 1.1.0).
GLOBAL-ID URL Parameter Works with International Sites
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).
Product Reference ID Format Change
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>
...
Documentation Changes and Errata - 1.1.0
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.
getDeals Removed from the Call Reference
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.
Version 1.0.0
This is the first release of the eBay Merchandising API.
For a current list of known issues, see Site Status and the Knowledge Base.
Index of Changed Calls - 1.0.0
These calls are included in the initial release of the eBay Merchandising API.