Skip to main content

The Recommendation API returns information that sellers can use to configure Promoted Listings ad campaigns.

The findListingRecommendations method returns the following response body for each returned listingId:

"listingRecommendations": [{
    "listingId": "{listingId}",
    "marketing": {
      "ad": {
        "bidPercentages": [{
          "basis": "TRENDING",
          "value": "{trendingAdRate}"
        }],
        "promoteWithAd": "[RECOMMENDED || UNDETERMINED]"
      },
      "message": "string"
    }
  }]

The above response body shows that findListingRecommendations returns two different recommendations for currently listed items:

  • promoteWithAd – This response field indicates whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign.
  • bidPercentages – Also known as the "ad rate," the bid percentage field provides the current trending bid percentage of similarly promoted items in the marketplace.

The promoteWithAd indicator

When and how promoteWithAd is returned depends on how you structure your findListingRecommendations request.

If returned, promoteWithAd returns either RECOMMENDED or UNDETERMINED for any specific listing.

RECOMMENDED means that by eBay's calculations, the listing has highest potential of benefiting from being included in a Promoted Listings ad campaign.

This recommendation is determined by reviewing current marketplace trends, such as buyer demand and the competition in the item’s category, and eBay suggests you promote the RECOMMENDED listings first, although you can promote any of your eligible listings for greater visibility.

UNDETERMINED means eBay cannot determine the level of advantage gained by including the associated listing in an ad campaign.

Tip: eBay cannot determine the promoteWithAd value for listings that are currently being promoted. To see the promoteWithAd value for a specific listing, first remove the listing from all ad campaigns.

The bidPercentage value

The bidPercentages field returns the current TRENDING "ad rate," which is calculated by averaging the ad rates of the listings that recently sold within the same category as the associated listing.

While eBay does not recommend the returned trending bid percentage as the optimum ad rate for your listing, you should consider this trending rate as a guide for how you set your own bidPercentage values.

Structuring a findListingRecommendations request

You can structure your findListingRecommendations requests to return recommendations for all of a seller's listings, or just the recommendations for a specific subset of the seller's listings.

In either case, the response is paginated to account for multiple returned listing IDs.

Getting recommendations for all of a seller's listings

If you do not include a request payload when you call findListingRecommendations, all of a seller's currently listed items are evaluated for recommendations. However, when all of a seller's listed items are considered, the request returns only those listings where promoteWithAd is set to RECOMMENDED.

If the promoteWithAd value is returned, the currently trending ad rate for each listing ID is also returned in the bidPercentages container.

Note: promoteWithAd values are not calculated for listing IDs that are part of an existing ad campaign.

Because calling findListingRecommendations in this manner (without a payload) returns only those listings whose promoteWithAd value is set to RECOMMENDED, the response does not include recommendations for listings already in a campaign. To see the trending ad rates for listings currently in a campaign, specify the listing IDs in the body of your call to findListingRecommendations.

For this request, set up the request headers then call the endpoint. All the query parameters are optional. If set, filter must be set to filter=recommendationTypes:{AD}, and you can use the limit and offest parameters to control the pagination of the response:

POST https://api.ebay.com/sell/recommendation/v1/find?
    filter=string&
    limit=integer&
    offset=integer

Tip: This is the best way to see which of your current listings are prime for being included in a Promoted Listings campaign.

Getting recommendations for a select set of listings

You can call findListingRecommendations with a set of up to 500 specific listing IDs. Structure your request with a payload similar to the following example, where you separate each listingId value you specify with a comma:

{
    "listingIds": [
        "260011362444", "260011362546", "260011362826"
    ]
}

With a few exceptions (such as the listing is already in a Promoted Listings campaign or the listing is not eligible to be in a campaign), eBay returns recommendations for all supplied listingId values. And again, the trending bid percentage is included with each returned ID.

Tip: This is the best way to see the trending ad rate for listings you are considering to promote.

The promoteWithAd value of either RECOMMENDED or UNDETERMINED is also returned for all listings, except for those listings that are currently being promoted. In cases where a listing ID is already being promoted, the bidPercentages container is returned, but the promoteWithAd field is not returned.