marketing APIv1_beta.1.0

getMerchandisedProducts

GET
/merchandised_product
This call returns an array of products based on the category and metric specified. This includes details of the product, such as the eBay product ID (EPID), title, and user reviews and ratings for the product. You can use the epid returned by this call in the Browse API search call to retrieve items for this product.

Restrictions

For a list of supported sites and other restrictions, see API Restrictions.

Input

Resource URI (production)

GET https://api.ebay.com/buy/marketing/v1_beta/merchandised_product?

URI parameters

ParameterTypeDescription
aspect_filterMarketingAspectFilterThe aspect name/value pairs used to further refine product results.

For example:
   /buy/marketing/v1_beta/merchandised_product?category_id=31388&metric_name=BEST_SELLING&aspect_filter=Brand:Canon

You can use the Browse API search call with the fieldgroups=ASPECT_REFINEMENTS field to return the aspects of a product.

Occurrence: Optional

limitstringThis value specifies the maximum number of products to return in a result set.

Note: Maximum value means the call will return up to that many products per set, but it can be less than this value. If the number of products found is less than this value, the call will return all of the products matching the criteria.

Default: 8
Maximum: 100

Occurrence: Optional

category_idstringThis query parameter limits the products returned to a specific eBay category.

The list of eBay category IDs is not published and category IDs are not all the same across all the eBay maketplace. You can use the following techniques to find a category by site.
  • Use the Category Changes page.
  • Use the Taxonomy API. For details see Categories for Buy API Calls.
  • Use the Browse API and submit the following call to get the dominantCategoryId for an item.
    /buy/browse/v1/item_summary/search?q=keyword&fieldgroups=ASPECT_REFINEMENTS
Maximum: 1
Required: 1

Occurrence: Required

metric_namestringThis value filters the result set by the specified metric. Only products in this metric are returned. Currently, the only metric supported is BEST_SELLING.

Default: BEST_SELLING
Maximum: 1
Required: 1

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the authorization HTTP header for authentication. See HTTP request headers - opens in a new tab for details.

OAuth scope

This request requires an Application access token with the following scope:

https://api.ebay.com/oauth/api_scope/buy.marketing

See Getting Access Tokens for more information.

Output

HTTP response headers

Output container/fieldTypeDescription
merchandisedProductsarray of MerchandisedProductAn array of containers for the products.

Occurrence: Conditional

merchandisedProducts.averageRatingstringThe average rating for the product based on eBay user ratings.

Occurrence: Conditional

merchandisedProducts.epidstringThe eBay product identifier of a product from the eBay product catalog. You can use this value in the Browse API search call to retrieve items for this product.

Occurrence: Conditional

merchandisedProducts.imageImageThe container for the product image.

Occurrence: Conditional

merchandisedProducts.image.heightinteger Reserved for future use.

Occurrence: Conditional

merchandisedProducts.image.imageUrlstringThe URL of the image.

Occurrence: Conditional

merchandisedProducts.image.widthinteger Reserved for future use.

Occurrence: Conditional

merchandisedProducts.marketPriceDetailsarray of MarketPriceDetailAn array of containers for the product market price details, such as condition and market price.

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.conditionGroupstringThe name for the condition of the product. For example: NEW

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.conditionIdsarray of stringAn array of condition identifiers for the product.

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.estimatedStartPriceAmountThe lowest priced active item for this product on eBay.

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.estimatedStartPrice.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field.

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.estimatedStartPrice.valuestringThe monetary amount, in the currency specified by the currency field.

Occurrence: Conditional

merchandisedProducts.ratingAspectsarray of RatingAspectAn array of containers for ratings of the product aspects, such as "Is it a good value".

Occurrence: Conditional

merchandisedProducts.ratingAspects.countintegerThe number of eBay users that rated the product on this aspect.

Occurrence: Conditional

merchandisedProducts.ratingAspects.descriptionstringThe name of the rating aspect. Camping tent examples: Is it lightweight? or Is it easy to set up?

Occurrence: Conditional

merchandisedProducts.ratingAspects.namestringThe answer or value of the rating aspect. Camping tent examples: Lightweight or Easy to set up

Occurrence: Conditional

merchandisedProducts.ratingAspects.ratingAspectDistributionsarray of RatingAspectDistributionThe container for the details of the aspect rating. The details show the aspect rating value, usually TRUE or FALSE and the user count and percentage.

Occurrence: Conditional

merchandisedProducts.ratingAspects.ratingAspectDistributions.countintegerThe number of eBay users that choose this rating aspect value.

Occurrence: Conditional

merchandisedProducts.ratingAspects.ratingAspectDistributions.percentagestringThe percentage of the aspect rating value.

ratingAspectDistributions.percentage = ratingAspectDistributions.count / ratingAspects.count

Occurrence: Conditional

merchandisedProducts.ratingAspects.ratingAspectDistributions.valuestringThe rating aspect. For example: TRUE or FALSE

Occurrence: Conditional

merchandisedProducts.ratingCountintegerThe total number of eBay users that rated the product.

Occurrence: Conditional

merchandisedProducts.reviewCountintegerThe total number of eBay users that wrote a review for the product.

Occurrence: Conditional

merchandisedProducts.titlestringThe title of the product.

Occurrence: Conditional

warningsarray of ErrorDetailV3The container with all the warnings for the input request.

Occurrence: Conditional

warnings.categorystringThis string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Conditional

warnings.domainstringThe name of the primary system where the error occurred. This is relevant for application errors.

Occurrence: Conditional

warnings.errorIdintegerA unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of stringAn array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.longMessagestringA detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

warnings.messagestringA description of the condition that caused the error or warning.

Occurrence: Conditional

warnings.outputRefIdsarray of stringAn array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3An array of warning and error messages that return one or more variables contextual information about the error or warning. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

warnings.parameters.namestringThis is the name of input field that caused an issue with the call request.

Occurrence: Conditional

warnings.parameters.valuestringThis is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstringThe name of the subdomain in which the error or warning occurred.

Occurrence: NA

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200OK
400Bad Request
500Internal Server Error

Error codes

CodeDomainCategoryMeaning
70000API_MARKETINGAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
70001API_MARKETINGREQUESTA metric_name is required to make the API call.
70002API_MARKETINGREQUESTThe metric_name {metric_name} is invalid.
70003API_MARKETINGREQUESTA categoryId is required to make the API call.
70004API_MARKETINGREQUESTThe category id {categoryId} is invalid
70005API_MARKETINGREQUESTThe 'limit' value should be between 1 and 100 (inclusive).
70006API_MARKETINGREQUESTThe 'limit' value must be an integer value.
70007API_MARKETINGBUSINESSThe marketplace value {marketplace} is not supported. The supported values are: {marketplaces}.

Samples

New to making API calls? Please see Making a Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample 1: Retrieve Best Selling Products

The call retrieves the best selling cameras.

Input

The inputs are the category_id and the metric_name.
GET
https://api.ebay.com/buy/marketing/v1_beta/merchandised_product?category_id=31388&metric_name=BEST_SELLING

Output

The output is an array of products and the details of the product, such as the eBay product ID (EPID), title, and user review and rating for the product.