Merchandising API

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:


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

Schema Changes - 1.5.0

Announcements - 1.5.0

New Features - 1.5.0

Changed Functionality - 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.

Back to top

Version 1.4.0

Index of Changed Calls - 1.4.0

Schema Changes - 1.4.0

Announcements - 1.4.0

New Features - 1.4.0

Changed Functionality - 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.

Back to top

Version 1.2.0

Index of Changed Calls - 1.2.0

Schema Changes - 1.2.0

Announcements - 1.2.0

New Features - 1.2.0

Changed Functionality - 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.

Back to top

Version 1.1.0

Index of Changed Calls - 1.1.0

Schema Changes - 1.1.0

Announcements - 1.1.0

New Features - 1.1.0

Changed Functionality - 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:

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.

Back to top

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.

New Calls





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.