--- title: Recommendation API description: "The **Recommendation API** returns information that sellers can use to configure Promoted Listings ad campaigns. **Note:** The Recommendation API only applies to general strategy campaigns that use the Cost Per Sale (CPS) funding model, and is currently only supported in the Australian (EBAY\\_AU), German (EBAY\\_DE), Great Britain (EBAY\\_GB), and United States (EBAY\\_US) eBay marketplaces. For details about creating and running ad campaigns, see [Promoted Listings](/api-docs/sell/static/marketing/promoted-listings.html) in the _Selling Integration Guide_." api_version: 1.0 api_name: recommendation_api api_type: REST api_group: sell/recommendation_api source_url: html: https://developer.ebay.com/develop/api/sell/recommendation_api md: https://developer.ebay.com/develop/api/sell/recommendation_api.md --- # Recommendation API API The **Recommendation API** returns information that sellers can use to configure Promoted Listings ad campaigns. **Note:** The Recommendation API only applies to general strategy campaigns that use the Cost Per Sale (CPS) funding model, and is currently only supported in the Australian (EBAY\_AU), German (EBAY\_DE), Great Britain (EBAY\_GB), and United States (EBAY\_US) eBay marketplaces. For details about creating and running ad campaigns, see [Promoted Listings](/api-docs/sell/static/marketing/promoted-listings.html) in the _Selling Integration Guide_. ## API Methods The following API methods are available: ### findListingRecommendations #### POST /find **Description:** The **find** method currently returns information for a single recommendation type (`AD`) which contains information that sellers can use to configure [Promoted Listings](/api-docs/sell/static/marketing/promoted-listings.html "Selling Integration Guide") ad campaigns. The response from this method includes an array of the seller's listing IDs, where each element in the array contains recommendations related to the associated listing ID. For details on how to use this method, see [Using the Recommendation API to help configure campaigns](/api-docs/sell/static/marketing/pl-reco-api.html "Selling Integration Guide"). **The AD recommendation type** The `AD` type contains two sets of information: * **The promoteWithAd indicator** The **promoteWithAd** response field indicates whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. The returned value is set to either `RECOMMENDED` or `UNDETERMINED`, where `RECOMMENDED` identifies the listings that will benefit the most from having them included in an ad campaign. * **The bid percentage** Also known as the "ad rate," the **bidPercentage** field provides the current trending bid percentage of similarly promoted items in the marketplace. The ad rate is a user-specified value that indicates the level of promotion that eBay applies to the campaign across the marketplace. The value is also used to calculate the Promotion Listings fee, which is assessed to the seller if a Promoted Listings action results in the sale of an item. **Configuring the request** You can configure a request to review all of a seller's currently active listings, or just a subset of them. * **All active listings** – If you leave the request body empty, the request targets _all_ the items currently listed by the seller. Here, the response is filtered to contain only the items where **promoteWithAd** equals `RECOMMENDED`. In this case, eBay recommends that all the returned listings should be included in a Promoted Listings ad campaign. * **Selected listing IDs** – If you populate the request body with a set of **listingIds**, the response contains data for all the specified listing IDs. In this scenario, the response provides you with information on listings where the **promoteWithAd** can be either `RECOMMENDED` or `UNDETERMINED`. **The paginated response** Because the response can contain many listing IDs, the **findListingRecommendations** method paginates the response set. You can control size of the returned pages, as well as an offset that dictates where to start the pagination, using query parameters in the request. **Parameters:** - **filter** (string) - Provide a list of key-value pairs to specify the criteria you want to use to filter the response. In the list, separate each filter key from its associated value with a colon ("`:`"). Currently, the only supported filter value is **recommendationTypes** and it supports only the ("`AD`") type. Follow the **recommendationTypes** specifier with the filter type(s) enclosed in curly braces ("`{ }`"), and separate multiple types with commas. **Example:** `filter=recommendationTypes:{AD}` **Default:** `recommendationTypes:{AD}` - **limit** (string) - Use this query parameter to set the maximum number of ads to return on a page from the paginated response. **Default:** 10 **Maximum:** 500 - **offset** (string) - Specifies the number of ads to skip in the result set before returning the first ad in the paginated response. Combine **offset** with the **limit** query parameter to control the items returned in the response. For example, if you supply an **offset** of `0` and a **limit** of `10`, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If **offset** is `10` and **limit** is `20`, the first page of the response contains items 11-30 from the complete result set. **Default:** 0 - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This header specifies the eBay marketplace where you list the items for which you want to get recommendations. See [HTTP Request Headers](/api-docs/static/rest-request-components.html#marketpl) for a list of supported eBay marketplace ID values. ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 145101 - API_RECOMMENDATION **Description:** The marketplace value {marketplaceId} is not supported. The supported values are: {marketplaceIds}. #### 145102 - API_RECOMMENDATION **Description:** Invalid value {recommendationTypes} for recommendationTypes filter. #### 145103 - API_RECOMMENDATION **Description:** You must specify at least one listing ID. #### 145104 - API_RECOMMENDATION **Description:** The recommendationTypes filter accepts a single value only. #### 145105 - API_RECOMMENDATION **Description:** Invalid listing Ids {listingIds}. #### 145106 - API_RECOMMENDATION **Description:** Listing ID limit exceeded. You can pass up to a maximum of 500 listing IDs per request. ### APPLICATION Errors #### 145000 - API_RECOMMENDATION **Description:** Internal error. Please wait a few minutes and try the call again. ## 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:26:57.049Z*