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
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
| Parameter | Type | Description |
|---|---|---|
| metric_name | string | This 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_id | string | This 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:
Maximum: 1 Required: 1 Occurrence: Required |
| limit | string | This 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_filter | MarketingAspectFilter | This 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/field | Type | Description |
|---|---|---|
| merchandisedProducts | array of MerchandisedProduct | An array of containers for the products. Occurrence: Conditional |
| merchandisedProducts.averageRating | string | The average rating for the product based on eBay user ratings. Occurrence: Conditional |
| merchandisedProducts.epid | string | 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.image | Image | The container for the product image. Occurrence: Conditional |
| merchandisedProducts.image.height | integer | Reserved for future use. Occurrence: Conditional |
| merchandisedProducts.image.imageUrl | string | The URL of the image. Occurrence: Conditional |
| merchandisedProducts.image.width | integer | Reserved for future use. Occurrence: Conditional |
| merchandisedProducts.marketPriceDetails | array of MarketPriceDetail | An array of containers for the product market price details, such as condition and market price. Occurrence: Conditional |
| merchandisedProducts.marketPriceDetails.conditionGroup | string | The name for the condition of the product. For example: NEW Occurrence: Conditional |
| merchandisedProducts.marketPriceDetails.conditionIds | array of string | An array of condition identifiers for the product. Occurrence: Conditional |
| merchandisedProducts.marketPriceDetails.estimatedStartPrice | Amount | The lowest priced active item for this product on eBay. Occurrence: Conditional |
| merchandisedProducts.marketPriceDetails.estimatedStartPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. Occurrence: Conditional |
| merchandisedProducts.marketPriceDetails.estimatedStartPrice.value | string | The monetary amount, in the currency specified by the currency field. Occurrence: Conditional |
| merchandisedProducts.ratingAspects | array of RatingAspect | An array of containers for ratings of the product aspects, such as "Is it a good value". Occurrence: Conditional |
| merchandisedProducts.ratingAspects.count | integer | The number of eBay users that rated the product on this aspect. Occurrence: Conditional |
| merchandisedProducts.ratingAspects.description | string | The name of the rating aspect. Camping tent examples: Is it lightweight? or Is it easy to set up? Occurrence: Conditional |
| merchandisedProducts.ratingAspects.name | string | The answer or value of the rating aspect. Camping tent examples: Lightweight or Easy to set up Occurrence: Conditional |
| merchandisedProducts.ratingAspects.ratingAspectDistributions | array 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.count | integer | The number of eBay users that choose this rating aspect value. Occurrence: Conditional |
| merchandisedProducts.ratingAspects.ratingAspectDistributions.percentage | string | The percentage of the aspect rating value. Occurrence: Conditional |
| merchandisedProducts.ratingAspects.ratingAspectDistributions.value | string | The rating aspect. For example: TRUE or FALSE Occurrence: Conditional |
| merchandisedProducts.ratingCount | integer | The total number of eBay users that rated the product. Occurrence: Conditional |
| merchandisedProducts.reviewCount | integer | The total number of eBay users that wrote a review for the product. Occurrence: Conditional |
| merchandisedProducts.title | string | The title of the product. Occurrence: Conditional |
| warnings | array of ErrorDetailV3 | The container with all the warnings for the input request. Occurrence: Conditional |
| warnings.category | string | This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. Occurrence: Always |
| warnings.domain | string | The name of the primary system where the error occurred. This is relevant for application errors. Occurrence: Always |
| warnings.errorId | integer | 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.inputRefIds | array 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.longMessage | string | 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.message | string | A description of the condition that caused the error or warning. Occurrence: Always |
| warnings.outputRefIds | array 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.parameters | array 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.name | string | This is the name of input field that caused an issue with the call request. Occurrence: Conditional |
| warnings.parameters.value | string | This is the actual value that was passed in for the element specified in the name field. Occurrence: Conditional |
| warnings.subdomain | string | 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.
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | Bad Request |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 70000 | API_MARKETING | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
| 70001 | API_MARKETING | REQUEST | A metric_name is required to make the API call. |
| 70002 | API_MARKETING | REQUEST | The metric_name {metric_name} is invalid. |
| 70003 | API_MARKETING | REQUEST | A categoryId is required to make the API call. |
| 70004 | API_MARKETING | REQUEST | The category id {categoryId} is invalid |
| 70005 | API_MARKETING | REQUEST | The 'limit' value should be between 1 and 100 (inclusive). |
| 70006 | API_MARKETING | REQUEST | The 'limit' value must be an integer value. |
| 70007 | API_MARKETING | BUSINESS | The 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.