{
"openapi": "3.0.0",
"info": {
"title": "Recommendation API",
"description": "The Recommendation API returns information that sellers can use to optimize the configuration of their listings on eBay.
Currently, the API contains a single method, findListingRecommendations. 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 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
type contains two sets of information:
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 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.
You can configure a request to review all of a seller's currently active listings, or just a subset of them.
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.
In this scenario, the response provides you with information on listings where the promoteWithAd can be either RECOMMENDED
or UNDETERMINED
.
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.",
"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.
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}
",
"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.
Default: 10
Maximum: 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.
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
", "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.ITEM
and TRENDING
are the only supported bid percentage types.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.TRENDING
suggested bid percentages are calculated by reviewing the category level average ad rates in the marketplace.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.
ITEM
and TRENDING
For implementation help, refer to eBay API documentation"
},
"value": {
"type": "string",
"description": "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
" } }, "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.Currently, this method accepts only listingId values from the Trading API.
Max: 500 listing IDs
", "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.AD
recommendation type, which contains information that sellers can use to configure Promoted Listings ad campaigns. AD
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 limit query parameter.",
"format": "int32"
},
"listingRecommendations": {
"type": "array",
"description": "Returns a list of listingRecommendations, where each element in the list offers recommendations for the associated listingId. RECOMMENDED
.",
"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. 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
.
0
.",
"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"
}
}
}
}
}
}
}