eBay Recommendation API
The eBay Recommendation API surfaces actionable recommendations sellers can apply to improve listing performance, such as enabling Promoted Listings.
OpenAPI Specification
openapi: 3.0.0
info:
title: eBay Recommendation API
description: The <b>Recommendation API</b> returns information that sellers can use to optimize the configuration of their listings on eBay. <br><br>Currently, the API contains a single method, <b>findListingRecommendations</b>. This method provides information that sellers can use to configure Promoted Listings ad campaigns to maximize the visibility of their items in the eBay marketplace.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.1.0
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/recommendation/v1
paths:
/find:
post:
tags:
- Listing_recommendation
description: The <b>find</b> method currently returns information for a single recommendation type (<code>AD</code>) which contains information that sellers can use to configure <a href="/api-docs/sell/static/marketing/promoted-listings.html" title="Selling Integration Guide">Promoted Listings</a> ad campaigns. <p>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 <a href="/api-docs/sell/static/marketing/pl-reco-api.html" title="Selling Integration Guide">Using the Recommendation API to help configure campaigns</a>.</p> <h3>The AD recommendation type</h3> </p> <p>The <code>AD</code> type contains two sets of information:</p> <ul><li><b>The promoteWithAd indicator</b> <br>The <b>promoteWithAd</b> response field indicates whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. <p>The returned value is set to either <code>RECOMMENDED</code> or <code>UNDETERMINED</code>, where <code>RECOMMENDED</code> identifies the listings that will benefit the most from having them included in an ad campaign.</p></li> <li><b>The bid percentage</b> <br>Also known as the "ad rate," the <b>bidPercentage</b> field provides the current trending bid percentage of similarly promoted items in the marketplace. <p>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.</p></li></ul> <h3>Configuring the request</h3> <p>You can configure a request to review all of a seller's currently active listings, or just a subset of them.</p> <ul><li><b>All active listings</b> – If you leave the request body empty, the request targets <i>all</i> the items currently listed by the seller. <p>Here, the response is filtered to contain only the items where <b>promoteWithAd</b> equals <code>RECOMMENDED</code>. In this case, eBay recommends that all the returned listings should be included in a Promoted Listings ad campaign.</p></li> <li><b>Selected listing IDs</b> – If you populate the request body with a set of <b>listingIds</b>, the response contains data for all the specified listing IDs. <p>In this scenario, the response provides you with information on listings where the <b>promoteWithAd</b> can be either <code>RECOMMENDED</code> or <code>UNDETERMINED</code>.</li></ul> <h3>The paginated response</h3> <p>Because the response can contain many listing IDs, the <b>findListingRecommendations</b> method paginates the response set.</p> <p>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.
operationId: findListingRecommendations
parameters:
- name: filter
in: query
description: Provide a list of key-value pairs to specify the criteria you want to use to filter the response. <br><br>In the list, separate each filter key from its associated value with a colon ("<code>:</code>"). <br><br>Currently, the only supported filter value is <b>recommendationTypes</b> and it supports only the ("<code>AD</code>") type. Follow the <b>recommendationTypes</b> specifier with the filter type(s) enclosed in curly braces ("<code>{ }</code>"), and separate multiple types with commas. <br><br><b>Example:</b> <code>filter=recommendationTypes:{AD}</code> <br><br><b>Default:</b> <code>recommendationTypes:{AD}</code>
required: false
schema:
type: string
- name: limit
in: query
description: 'Use this query parameter to set the maximum number of ads to return on a page from the paginated response. <br><br><b>Default: </b>10 <br><b>Maximum:</b> 500'
required: false
schema:
type: string
- name: offset
in: query
description: Specifies the number of ads to skip in the result set before returning the first ad in the paginated response. <p>Combine <b>offset</b> with the <b>limit</b> query parameter to control the items returned in the response. For example, if you supply an <b>offset</b> of <code>0</code> and a <b>limit</b> of <code>10</code>, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If <b>offset</b> is <code>10</code> and <b>limit</b> is <code>20</code>, the first page of the response contains items 11-30 from the complete result set.</p> <p><b>Default:</b> 0</p>
required: false
schema:
type: string
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: This header specifies the eBay marketplace where you list the items for which you want to get recommendations.<br><br>See <a href="/api-docs/static/rest-request-components.html#marketpl" target="_blank">HTTP Request Headers</a> for a list of supported eBay marketplace ID values.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FindListingRecommendationRequest'
required: false
responses:
'200':
description: Success
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/PagedListingRecommendationCollection'
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'145101':
domain: API_RECOMMENDATION
category: REQUEST
description: 'The marketplace value {marketplaceId} is not supported. The supported values are: {marketplaceIds}. '
'145102':
domain: API_RECOMMENDATION
category: REQUEST
description: Invalid value {recommendationTypes} for recommendationTypes filter
'145103':
domain: API_RECOMMENDATION
category: REQUEST
description: You must specify at least one listing ID.
'145104':
domain: API_RECOMMENDATION
category: REQUEST
description: The recommendationTypes filter accepts a single value only.
'145105':
domain: API_RECOMMENDATION
category: REQUEST
description: Invalid listing Ids {listingIds}.
'145106':
domain: API_RECOMMENDATION
category: REQUEST
description: Listing ID limit exceeded. You can pass up to a maximum of 500 listing IDs per request.
'500':
description: Internal Server Error
x-response-codes:
errors:
'145000':
domain: API_RECOMMENDATION
category: APPLICATION
description: Internal error. Please wait a few minutes and try the call again
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
components:
schemas:
Ad:
type: object
properties:
bidPercentages:
type: array
description: This field returns information that you can use to configure the <b>bidPercentage</b> field in a Promoted Listings campaign.<br /><br /><span class="tablenote"><b>Note:</b> Currently, <code>ITEM</code> and <code>TRENDING</code> are the only supported bid percentage types.</span><br /><br />The <code>ITEM</code> 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.<br /><br />The <code>TRENDING</code> suggested bid percentages are calculated by reviewing the category level average ad rates in the marketplace.<br /><br />Setting the <b>bidPercentage</b> 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.
items:
$ref: '#/components/schemas/BidPercentages'
promoteWithAd:
type: string
description: An enum whose values describe whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. <br><br>IDs deemed <code>RECOMMENDED</code> 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. <p class="tablenote"><b>Note:</b> A <b>promoteWithAd</b> value cannot be calculated for listings that are part of Promoted Listings campaigns. <br><br>Because of this, if you call <b>findListingRecommendations</b> with a specific set of listing IDs, the <b>promoteWithAd</b> field is not returned for any of the listings that are involved in a promotion. However, as long as they are eligible, the trending <b>bidPercentage</b> <i>is</i> returned for all specified listings, even if they are part of an ad campaign.</p> For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/recommendation/types/api:PromoteWithAd'>eBay API documentation</a>
description: A complex type that contains recommendations and information on how to configure Promoted Listings ad campaigns.
BidPercentages:
type: object
properties:
basis:
type: string
description: The basis by which the ad rate is calculated.<br /><br /><b>Valid Values:</b> <code>ITEM</code> and <code>TRENDING</code> For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/recommendation/types/api:Basis'>eBay API documentation</a>
value:
type: string
description: The bid percentage data is a single precision value, as calculated by the associated basis. <p>In Promoted listings ad campaigns, the <b>bid percentage</b> (also known as the <i>ad rate</i>) 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.</p> <p><b>Minimum value:</b> 1.0 <b>Maximum value:</b> 100.0</p>
description: A complex type that returns data related to Promoted Listings bid percentages.
Error:
type: object
properties:
category:
type: string
description: Identifies the type of erro.
domain:
type: string
description: Name for the primary system where the error occurred. This is relevant for application errors.
errorId:
type: integer
description: A unique number to identify the error.
format: int32
inputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
longMessage:
type: string
description: A more detailed explanation of the error.
message:
type: string
description: Information on how to correct the problem, in the end user's terms and language where applicable.
outputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
parameters:
type: array
description: An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.
items:
$ref: '#/components/schemas/ErrorParameter'
subdomain:
type: string
description: 'Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.'
description: This type defines the fields that can be returned in an error.
ErrorParameter:
type: object
properties:
name:
type: string
description: The object of the error.
value:
type: string
description: The value of the object.
FindListingRecommendationRequest:
type: object
properties:
listingIds:
type: array
description: A comma-separated list of listing IDs for which you want Promoted Listings ad configuration information. <p>Currently, this method accepts only <b>listingId</b> values from the Trading API.</p> <p><b>Max:</b> 500 listing IDs</p>
items:
type: string
description: An list of listing ID values for which you want Promoted Listings ad configuration information.
ListingRecommendation:
type: object
properties:
listingId:
type: string
description: An ID that identifies the active listing associated with the eBay recommendations.
marketing:
description: 'This return object provides the eBay recommendations and information related to the associated listing ID. <br><br>The container currently returns the <code>AD</code> recommendation type, which contains information that sellers can use to configure Promoted Listings ad campaigns. <br><br>This container is returned with each <b>ListingRecommendation</b> object, <i>except</i> when: <ul><li>The listing ID is not eligible for Promoted Listings</li> <li>The listing ID is currently in a Promoted Listings campaign</li> <li>The listing ID is invalid</li></ul>'
$ref: '#/components/schemas/MarketingRecommendation'
description: A complex type that contains the ID of an actively listed item and a set of related listing recommendations. The recommendations contain information the seller can use to optimize their listing configurations.
MarketingRecommendation:
type: object
properties:
ad:
description: An object that contains Promoted Listings recommendations and information related to the associated listing ID.
$ref: '#/components/schemas/Ad'
message:
type: string
description: A message that can conditionally accompany the listing information.
description: A complex type that contains information about how a seller can improve their listing configurations. The <code>AD</code> object contains Promoted Listings recommendations and information, which the seller can use to improve buyer conversions. The response can also contain an optional message about the returned data.
PagedListingRecommendationCollection:
type: object
properties:
href:
type: string
description: The URI of the current page of results from the result set.
limit:
type: integer
description: The number of items returned on a single page from the result set. This value can be set in the request with the <b>limit</b> query parameter.
format: int32
listingRecommendations:
type: array
description: Returns a list of <b>listingRecommendations</b>, where each element in the list offers recommendations for the associated <b>listingId</b>. <br><br>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), <b>ad</b> recommendations are returned only for those listings where <b>promoteWithAd</b> is set to <code>RECOMMENDED</code>.
items:
$ref: '#/components/schemas/ListingRecommendation'
next:
type: string
description: '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. <br><br><b>Max length</b>: 2048'
offset:
type: integer
description: '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 <b>offset</b> query parameter. <p class="tablenote"><strong>Note: </strong>The items in a paginated result set use a zero-based list where the first item in the list has an offset of <code>0</code>.</p>'
format: int32
prev:
type: string
description: '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. <br><br><b>Max length</b>: 2048'
total:
type: integer
description: The total number of items retrieved in the result set. <br><br>If no items are found, this field is returned with a value of <code>0</code>.
format: int32
description: The high-level object used to return a set of Promoted Listings ad recommendations.
securitySchemes:
api_auth:
type: oauth2
description: The security definitions for this API. Please check individual operations for applicable scopes.
flows:
authorizationCode:
authorizationUrl: https://auth.ebay.com/oauth2/authorize
tokenUrl: https://api.ebay.com/identity/v1/oauth2/token
scopes:
https://api.ebay.com/oauth/api_scope/sell.inventory: View and manage your inventory and offers
tags:
- name: Listing_recommendation