Skip to main content

GET/merchandised_product

This method 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 method in the Browse API search method to retrieve items for this product.

Restrictions

  • To test getMerchandisedProducts in Sandbox, you must use category ID 9355 and the response will be mock data.
  • For a list of supported sites and other restrictions, see API Restrictions.

Input

Resource URI

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

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

ParameterTypeDescription
metric_namestringThis value filters the result set by the specified metric. Only products in this metric are returned.

Note: Currently, the only metric supported is BEST_SELLING.
Default: BEST_SELLING

Maximum: 1

Required: 1

Occurrence: Required

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 Get Categories for Buy APIs.
  • Use the Browse API and submit the following method to get the dominantCategoryId for an item.
    /buy/browse/v1/item_summary/search?q=keyword&fieldgroups=ASPECT_REFINEMENTS

Maximum: 1

Required: 1

Occurrence: Required

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

Note: Maximum value means the method 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 method will return all of the products matching the criteria.
Default: 8

Maximum: 100

Occurrence: Optional

aspect_filterMarketingAspectFilterThis value specifies the 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 method with the fieldgroups=ASPECT_REFINEMENTS field to return the aspects of a product.

Occurrence: Optional

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.

OAuth scope

This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

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

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Response fields

Output container/fieldTypeDescription
merchandisedProductsarray of MerchandisedProduct

An array of containers for the products.

Occurrence: Conditional

merchandisedProducts.averageRatingstring

The average rating for the product based on eBay user ratings.

Occurrence: Conditional

merchandisedProducts.epidstring

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

Occurrence: Conditional

merchandisedProducts.imageImage

The container for the product image.

Occurrence: Conditional

merchandisedProducts.image.heightinteger

Reserved for future use.

Occurrence: Conditional

merchandisedProducts.image.imageUrlstring

The URL of the image.

Occurrence: Conditional

merchandisedProducts.image.widthinteger

Reserved for future use.

Occurrence: Conditional

merchandisedProducts.marketPriceDetailsarray of MarketPriceDetail

An array of containers for the product market price details, such as condition and market price.

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.conditionGroupstring

The name for the condition of the product. For example: NEW

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.conditionIdsarray of string

An array of condition identifiers for the product.

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.estimatedStartPriceAmount

The lowest priced active item for this product on eBay.

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.estimatedStartPrice.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field.

Occurrence: Conditional

merchandisedProducts.marketPriceDetails.estimatedStartPrice.valuestring

The monetary amount, in the currency specified by the currency field.

Occurrence: Conditional

merchandisedProducts.ratingAspectsarray of RatingAspect

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

Occurrence: Conditional

merchandisedProducts.ratingAspects.countinteger

The number of eBay users that rated the product on this aspect.

Occurrence: Conditional

merchandisedProducts.ratingAspects.descriptionstring

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

Occurrence: Conditional

merchandisedProducts.ratingAspects.namestring

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

Occurrence: Conditional

merchandisedProducts.ratingAspects.ratingAspectDistributionsarray of RatingAspectDistribution

The 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.countinteger

The number of eBay users that choose this rating aspect value.

Occurrence: Conditional

merchandisedProducts.ratingAspects.ratingAspectDistributions.percentagestring

The percentage of the aspect rating value.

ratingAspectDistributions.percentage = ratingAspectDistributions.count / ratingAspects.count

Occurrence: Conditional

merchandisedProducts.ratingAspects.ratingAspectDistributions.valuestring

The rating aspect. For example: TRUE or FALSE

Occurrence: Conditional

merchandisedProducts.ratingCountinteger

The total number of eBay users that rated the product.

Occurrence: Conditional

merchandisedProducts.reviewCountinteger

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

Occurrence: Conditional

merchandisedProducts.titlestring

The title of the product.

Occurrence: Conditional

warningsarray of ErrorDetailV3

The container with all the warnings for the input request.

Occurrence: Conditional

warnings.categorystring

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

Occurrence: Always

warnings.domainstring

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

Occurrence: Always

warnings.errorIdinteger

A 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: Always

warnings.inputRefIdsarray of string

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

Occurrence: Conditional

warnings.longMessagestring

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

Occurrence: Conditional

warnings.messagestring

A description of the condition that caused the error or warning.

Occurrence: Always

warnings.outputRefIdsarray of string

An 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 ErrorParameterV3

An 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.namestring

This is the name of input field that caused an issue with the call request.

Occurrence: Conditional

warnings.parameters.valuestring

This is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstring

The 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

For more on errors, plus the codes of other common errors, see Handling errors.

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}.

Warnings

This call has no warnings.

Samples

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

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant 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.

GEThttps://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.

Sample 2: Retrieve Best Selling Products by Aspect

The call retrieves the best selling Cannon cameras.

Input

The inputs are the category_id, the metric_name, and aspect_filter, which refines the results to Cannon cameras.

GEThttps://api.ebay.com/buy/marketing/v1_beta/merchandised_product?category_id=31388&metric_name=BEST_SELLING&aspect_filter=Brand:Canon

Output

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

Got thoughts? Click the feedback button – your insights help us improve!