--- title: Marketing Beta API description: "The Marketing Beta API is part of the eBay Buy APIs. It retrieves eBay products based on a metric, such as Best Selling. This API helps shoppers compare products and motivate them to purchase items. You can use the other [Buy APIs](https://developer.ebay.com/api-docs/buy/static/buy-overview.html) to create a buying application that lets users, eBay members or guests, buy from eBay sellers without visiting the eBay site. The Buy APIs provide the opportunity to purchase eBay items in your app or website." api_version: 1.0 api_name: marketing_beta_api api_type: REST api_group: buy/marketing_beta_api source_url: html: https://developer.ebay.com/develop/api/buy/marketing_beta_api md: https://developer.ebay.com/develop/api/buy/marketing_beta_api.md --- # Marketing Beta API API The Marketing Beta API is part of the eBay Buy APIs. It retrieves eBay products based on a metric, such as Best Selling. This API helps shoppers compare products and motivate them to purchase items. You can use the other [Buy APIs](https://developer.ebay.com/api-docs/buy/static/buy-overview.html) to create a buying application that lets users, eBay members or guests, buy from eBay sellers without visiting the eBay site. The Buy APIs provide the opportunity to purchase eBay items in your app or website. ## API Methods The following API methods are available: ### getMerchandisedProducts #### GET /merchandised_product **Description:** 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 [Buy API Support by Marketplace](/api-docs/buy/static/ref-marketplace-supported.html). **Parameters:** - **aspect_filter** (string) - This value specifies the aspect name/value pairs used to refine product results. For example, the following would specify the brand to be returned: /buy/marketing/v1\_beta/merchandised\_product?category\_id=31388&metric\_name=BEST\_SELLING&aspect\_filter=Brand:Canon You can also filter by multiple aspects using a comma-delimited list such as the following: /buy/marketing/v1\_beta/merchandised\_product?category\_id=31388&metric\_name=BEST\_SELLING&aspect\_filter=Color:Black,Brand:Nikon This returns products that match both filters. **Note**: Multiple values for the same aspect filter are _not_ supported. For example, if you specify multiple values for the same aspect, only the last value will be used by the API. In the following example, only the last brand specified (Nikon) will be returned: /buy/marketing/v1\_beta/merchandised\_product?category\_id=31388&metric\_name=BEST\_SELLING&aspect\_filter=Brand:Canon,Brand:Nikon To retrieve products for multiple values of the same aspect, make separate API calls for each filter value. You can use the **Browse API's** [search](/develop/api/buy/browse_api#buy-browse_api-item_summary-search) method with the `fieldgroups=ASPECT_REFINEMENTS` field to return the aspects of a product. - **category_id** (string) *required* - 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: * Use the [Category Changes page](https://pages.ebay.com/sellerinformation/news/categorychanges.html). * Use the Taxonomy API. For details see [Get Categories for Buy APIs](/api-docs/buy/buy-categories.html). * 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 - **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 - **metric_name** (string) *required* - 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 ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 70001 - API_MARKETING **Description:** A metric\_name is required to make the API call. #### 70002 - API_MARKETING **Description:** The metric\_name {metric\_name} is invalid. #### 70003 - API_MARKETING **Description:** A categoryId is required to make the API call. #### 70004 - API_MARKETING **Description:** The category id {categoryId} is invalid #### 70005 - API_MARKETING **Description:** The 'limit' value should be between 1 and 100 (inclusive). #### 70006 - API_MARKETING **Description:** The 'limit' value must be an integer value. ### BUSINESS Errors #### 70007 - API_MARKETING **Description:** The marketplace value {marketplace} is not supported. The supported values are: {marketplaces}. ### APPLICATION Errors #### 70000 - API_MARKETING **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-07-08T04:46:17.734Z*