findListingRecommendations: eBay Recommendation API

POST/find

The find method currently returns information for a single recommendation type (AD) which contains information that sellers can use to configure Promoted Listings 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.

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.

Input

Resource URI

POST https://api.ebay.com/sell/recommendation/v1/find?

filter=string&

limit=integer&

offset=integer

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
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}` Occurrence: Optional
limit	integer	Use this query parameter to set the maximum number of ads to return on a page from the paginated response. Default: 10 Maximum: 500 Occurrence: Optional
offset	integer	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 Occurrence: Optional

HTTP request headers

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

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header	Type	Description
X-EBAY-C-MARKETPLACE-ID	string	This header specifies the eBay marketplace where you list the items for which you want to get recommendations. See HTTP Request Headers for a list of supported eBay marketplace ID values. Occurrence: Required

Header

Type

Description

X-EBAY-C-MARKETPLACE-ID

string

This header specifies the eBay marketplace where you list the items for which you want to get recommendations.

See HTTP Request Headers for a list of supported eBay marketplace ID values.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code 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/sell.inventory

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

{ /* FindListingRecommendationRequest */

"listingIds" : [

"string"

]

}

Request fields

Input container/field	Type	Description
listingIds	array of string	A comma-separated list of listing IDs for which you want Promoted Listings ad configuration information. Currently, this method accepts only listingId values from the Trading API. Max: 500 listing IDs Occurrence: Optional

Input container/field

Type

Description

listingIds

array of string

A comma-separated list of listing IDs for which you want Promoted Listings ad configuration information.

Currently, this method accepts only listingId values from the Trading API.

Max: 500 listing IDs

Occurrence: Optional

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* PagedListingRecommendationCollection */

"href" : "string",

"limit" : "integer",

"listingRecommendations" : [

{ /* ListingRecommendation */

"listingId" : "string",

"marketing" :

{ /* MarketingRecommendation */

"ad" :

{ /* Ad */

"bidPercentages" : [

{ /* BidPercentages */

"basis" : "Basis : [ITEM,TRENDING]",

"value" : "string"

}

"promoteWithAd" : "PromoteWithAd : [RECOMMENDED,UNDETERMINED]"

"message" : "string"

}

"next" : "string",

"offset" : "integer",

"prev" : "string",

"total" : "integer"

}

Response fields

Output container/field	Type	Description
href	string	The URI of the current page of results from the result set. Occurrence: Conditional
limit	integer	The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter. Occurrence: Conditional
listingRecommendations	array of ListingRecommendation	Returns a list of listingRecommendations, where each element in the list offers recommendations for the associated listingId. Which elements are returned depend on how you structure the request. For example, if you request recommendations for all of a sellers listings (by leaving the request payload empty), ad recommendations are returned only for those listings where promoteWithAd is set to `RECOMMENDED`. Occurrence: Conditional
listingRecommendations.listingId	string	An ID that identifies the active listing associated with the eBay recommendations. Occurrence: Conditional
listingRecommendations.marketing	MarketingRecommendation	This return object provides the eBay recommendations and information related to the associated listing ID. The container currently returns the `AD` recommendation type, which contains information that sellers can use to configure Promoted Listings ad campaigns. This container is returned with each ListingRecommendation object, except when: The listing ID is not eligible for Promoted Listings The listing ID is currently in a Promoted Listings campaign The listing ID is invalid Occurrence: Conditional
listingRecommendations.marketing.ad	Ad	An object that contains Promoted Listings recommendations and information related to the associated listing ID. Occurrence: Conditional
listingRecommendations.marketing.ad.bidPercentages	array of BidPercentages	This field returns information that you can use to configure the bidPercentage field in a Promoted Listings campaign. Note: Currently, `ITEM` and `TRENDING` are the only supported bid percentage types. The `ITEM` suggested bid percentages are tailored to each of your items and are designed to help you stay competitive while finding an optimal balance between performance and cost. The recommendations are calculated based on a variety of factors that may include item attributes, seasonality, past performance, and current competition for each of your listings. The `TRENDING` suggested bid percentages are calculated by reviewing the category level average ad rates in the marketplace. Setting the bidPercentage of your ad campaign based on these rate recommendations will help the items in the campaign be competitive with other items in the marketplace by improving their chances of being displayed more often in the marketplace. Occurrence: Conditional
listingRecommendations.marketing.ad.bidPercentages.basis	Basis	The basis by which the ad rate is calculated. Valid Values: `ITEM` and `TRENDING` Occurrence: Conditional
listingRecommendations.marketing.ad.bidPercentages.value	string	The bid percentage data is a single precision value, as calculated by the associated basis. In Promoted listings ad campaigns, the bid percentage (also known as the ad rate) is a user-defined value that sets the level that eBay raises the visibility of the listing in the marketplace. It is also the rate that is used to calculate the Promoted Listings fee. Minimum value: 1.0 Maximum value: 100.0 Occurrence: Conditional
listingRecommendations.marketing.ad.promoteWithAd	PromoteWithAd	An enum whose values describe whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. IDs deemed `RECOMMENDED` by eBay are the listings with the highest potential of benefiting from being promoted. The recommendation calculation is based on marketplace trends, like buyer demand and the competition in the item’s category. Note: A promoteWithAd value cannot be calculated for listings that are part of Promoted Listings campaigns. Because of this, if you call findListingRecommendations with a specific set of listing IDs, the promoteWithAd field is not returned for any of the listings that are involved in a promotion. However, as long as they are eligible, the trending bidPercentage is returned for all specified listings, even if they are part of an ad campaign. Occurrence: Conditional
listingRecommendations.marketing.message	string	A message that can conditionally accompany the listing information. Occurrence: Conditional
next	string	The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set. Max length: 2048 Occurrence: Conditional
offset	integer	The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of `0`. Occurrence: Conditional
prev	string	The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set. Max length: 2048 Occurrence: Conditional
total	integer	The total number of items retrieved in the result set. If no items are found, this field is returned with a value of `0`. Occurrence: Conditional

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	Success
204	No Content
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
145000	API_RECOMMENDATION	APPLICATION	Internal error. Please wait a few minutes and try the call again
145101	API_RECOMMENDATION	REQUEST	The marketplace value {marketplaceId} is not supported. The supported values are: {marketplaceIds}.
145102	API_RECOMMENDATION	REQUEST	Invalid value {recommendationTypes} for recommendationTypes filter
145103	API_RECOMMENDATION	REQUEST	You must specify at least one listing ID.
145104	API_RECOMMENDATION	REQUEST	The recommendationTypes filter accepts a single value only.
145105	API_RECOMMENDATION	REQUEST	Invalid listing Ids {listingIds}.
145106	API_RECOMMENDATION	REQUEST	Listing ID limit exceeded. You can pass up to a maximum of 500 listing IDs per request.

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: Get ad recommendations for a seller

Sample 2: Get ad recommendations by listing IDs

Sample 1: Get ad recommendations for a seller

This sample makes a request for ad recommendations for a seller.

Input

There is no call payload for this request. Populate the X-EBAY-C-MARKETPLACE-ID header with the marketplace you want to use and set the endpoint as shown.

POSThttps://api.ebay.com/sell/recommendation/v1/find?filter=recommendationTypes:{AD}&offset=0&limit=25

Output

If the call is successful, it returns all the listing IDs where the promoteWithAd equals RECOMMENDED, which is the listings that eBay recommends you place in a Promoted Listings ad campaign.

{
    "offset": 0,
    "href": "<currentURL>",
    "total": 1,
    "limit": 25,
    "listingRecommendations": [
        {
            "listingId": "2********4",
            "promotedWithAd": "RECOMMENDED",
            "marketing": {
                "ad": {
                    "bidPercentages": [
                        {
                            "value": "6.2",
                            "basis": "TRENDING"
                        },
                        {
                            "value": "7.2",
                            "basis": "ITEM"
                        }
                    ]
                }
            }
        },
        {
            "listingId": "2********5",
            "promotedWithAd": "UNDETERMINED",
            "marketing": {
                "ad": {
                    "bidPercentages": [
                        {
                            "value": "4.4",
                            "basis": "TRENDING"
                        },
                        {
                            "value": "4.4",
                            "basis": "ITEM"
                        }
                    ]
                }
            }
        }
    ]
}

Sample 2: Get ad recommendations by listing IDs

This sample requests recommendations for a specified set of listing IDs.

Input

Unlike the previous sample, this sample requests recommendations for a specific list of Trading API listingId values. Supply your listing IDs as a comma-separated list in the request body and set the X-EBAY-C-MARKETPLACE-ID header to the marketplace where you list the items.

POSThttps://api.ebay.com/sell/recommendation/v1/find?filter=recommendationTypes:{AD}

Output

If the call is successful, ad recommendations will be returned for all the listing IDs supplied in the request.