Making a Call
Note: The Listing Recommendation API is scheduled for deprecation. We recommend you integrate with the the new Recommendation API to retrieve recommendations for improving your listings and sales performance, or with the Compliance API to discover non-compliant listings or listings that are at risk at becoming non-compliant in the future. |
This document explains how to make Listing Recommendation API calls. It provides an overview of the calls, supported data formats, HTTPS headers, URL parameters, and call endpoints.
Introduction to API
Listing Recommendation API is a REST-based API that is used by eBay sellers to retrieve eBay-generated listing recommendations. These listing recommendations can then be used by the seller to improve or bring listings up to standard in regards to top-rated seller/listing requirements, mandated or recommended Item Specifics, mandated or recommended Product Identifier, picture quality requirements, pricing and/or listing format recommendations, recommended keywords and/or Item Specifics in a Title, and/or a recommendation to use Fast 'N Free shipping.
High-level information for the API are covered below, including call endpoints, HTTPS headers and URL parameters, naming conventions, and versioning scheme.
- Call Endpoints—Each call uses an HTTPS GET request. The base endpoint for the Production version of the Listing
Recommendation API is:
https://svcs.ebay.com/services/selling/listingrecommendation
The initial version of the Listing Recommendation API is not available in the Sandbox environment.
Each call has a different endpoint, and these endpoints are covered in the Call Endpoints section. - HTTPS Headers—Each Listing Recommendation API call requires an
Authorization
HTTPS header. TheAuthorization
token value should be pre-fixed byTOKEN
, so the complete value looks like:TOKEN
<authorization token value>. Through an optionalAccept
HTTPS header, the seller can control whether the response is returned in JSON or XML format. If theAccept
HTTPS header is not used, the default response format is JSON. - Naming conventions—The naming conventions for the Listing Recommendation API are slightly different than the Trading API. Most notably, call names and fields in the Listing Recommendation API begin with lowercase letters.
- Versioning scheme—The version numbering scheme for the Listing Recommendation
API is different from the scheme used by the eBay Shopping and Trading APIs. The Listing
Recommendation API version consists of three digits (e.g., 1.2.3):
- The first digit indicates the major release version. Major releases are not backward compatible.
- The second digit indicates the minor release version. Minor releases consist of feature additions or behavior changes that are backward compatible.
- The third digit indicates the maintenance, or micro release version. Maintenance releases are used to correct minor problems. Maintenance releases have minimal impact on the features or functionality of the API.
Supported Data Formats
Supported Request Format
The Listing Recommendation API only supports HTTPS GET requests.
Supported Response Formats
The Listing Recommendation API supports JSON and XML response formats.
The reponse format is set with the Accept HTTPS header value in the request. The Accept value can be set to "application/json" or "application/xml". The response format defaults to JSON if the Accept HTTPS header is not included in the request.
Call Structure
Each Listing Recommendation API call consists of the following elements:
- Call Endpoint—Each call has a different endpoint, and these endpoints are covered in the Call Endpoints section. Remember that the initial version of the Listing Recommendation API is not supported in the Sandbox environment.
- HTTPS Headers—Required and optional HTTPS headers vary for each Listing Recommendation API call. See the subsequent sections for information on the HTTPS headers used for each call.
- URL Parameters—Required and optional HTTPS headers vary for each Listing Recommendation API call. See the subsequent sections for information on the URL parameters used for each call.
HTTPS Request Headers and Input Parameters for the latestVersion Call
HTTPS Headers:
Header | Applicable Value(s) | Required? |
---|---|---|
Authorization | A valid eBay authorization token, prefixed by 'TOKEN ' (TOKEN <authorization token value>) |
Yes |
Accept | "application/json" or "application/xml" | No |
Input Parameters:
None.
HTTPS Request Headers and Input Parameters for the recommendationsSummary Call
HTTPS Headers:
Header | Applicable Value(s) | Required? |
---|---|---|
Authorization | A valid eBay authorization token, prefixed by 'TOKEN ' (TOKEN <authorization token value>) |
Yes |
X-EBAY-GLOBAL-ID | A valid Global ID value for an eBay site (such as "EBAY-US"). This value defaults to "EBAY-US" if this header is not included in the request. For a list of valid eBay Site IDs, see the Global ID Values page. | No |
Accept | "application/json" or "application/xml" | No |
Input Parameters:
None.
HTTPS Request Headers and Input Parameters for the recommendationItemIds Call
HTTPS Headers:
Header | Applicable Value(s) | Required? |
---|---|---|
Authorization | A valid eBay authorization token, prefixed by 'TOKEN ' (TOKEN <authorization token value>) |
Yes |
X-EBAY-GLOBAL-ID | A valid Global ID value for an eBay site (such as "EBAY-US"). This value defaults to "EBAY-US" if this header is not included in the request. For a list of valid eBay Site IDs, see the Global ID Values page. | No |
Accept | "application/json" or "application/xml" | No |
Input Parameters:
Input Parameter | Type | Applicable Value(s) | Required? |
---|---|---|---|
recommendationType | String | eTRS , ItemSpecifics , ProductIdentifier , Picture , Price , Title , or FnF (Fast 'N Free shipping) |
Yes |
pageNumber | Int | A positive integer value within the range of pages returned | Yes |
entriesPerPage | Int | A positive integer value between 1 and 5000 (default is 2500) | No |
HTTPS Request Headers and Input Parameters for the itemRecommendations Call
HTTPS Headers:
Header | Applicable Value(s) | Required? |
---|---|---|
Authorization | A valid eBay authorization token, prefixed by 'TOKEN ' (TOKEN <authorization token value>) |
Yes |
Accept | "application/json" or "application/xml" | No |
Input Parameters:
Input Parameter | Type | Applicable Value(s) | Required? |
---|---|---|---|
recommendationType | String | All , eTRS , ItemSpecifics , ProductIdentifier , Picture , Price , Title , or FnF (Fast 'N Free shipping). Any one or combination of these values may be used. All is used by default if no type is specified. |
Yes |
Call Endpoints
Each Listing Recommendation API call request has a different endpoint. These endpoints are discussed in the subsequent sections. Remember that the initial version of the Listing Recommendation API is not supported in the Sandbox environment, so all call endpoints in the subsequent sections are Production endpoints.
latestVersion Endpoint
https://svcs.ebay.com/services/selling/listingrecommendation/latestVersion
Note: The endpoint for this call is always the same, as no version number is required. |
recommendationsSummary Endpoint
https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/recommendationsSummary
Note: The call endpoint contains the major version for the service (e.g., v1). When updating to subsequent major releases, you must update the version in the call endpoint. |
recommendationItemIds Endpoint
https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/recommendationItemIds?recommendationType=<string_value>&pageNumber=<int_value>&entriesPerPage=<int_value>
The recommendationType and pageNumber values are required, and the entriesPerPage value is optional.
Note: The call endpoint contains the major version for the service (e.g., v1). When updating to subsequent major releases, you must update the version in the call endpoint. |
itemRecommendations Endpoint
https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/<ItemID_value>/itemRecommendations?recommendationType=<string_value>
An Item ID value is required as part of the path, and the
recommendationType value is optional. Any of the following values (or
combination of values) may be used for recommendationType: All
, eTRS
, ItemSpecifics
, ProductIdentifier
, Picture
, Price
, Title
, or FnF
(Fast 'N Free shipping).
Note: The Item ID used in the call endpoint must be for a listing owned by the seller, or the call will fail. |