Making a Call

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
• Supported Data Formats
  • Supported Request Format
  • Supported Response Formats
• Call Structure
  • HTTPS Request Headers and Input Parameters for the latestVersion Call
  • HTTPS Request Headers and Input Parameters for the recommendationsSummary Call
  • HTTPS Request Headers and Input Parameters for the recommendationItemIds Call
  • HTTPS Request Headers and Input Parameters for the itemRecommendations Call
• Call Endpoints
  • latestVersion Endpoint
  • recommendationsSummary Endpoint
  • recommendationItemIds Endpoint
  • itemRecommendations Endpoint

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. The Authorization token value should be pre-fixed by TOKEN, so the complete value looks like: TOKEN <authorization token value>. Through an optional Accept HTTPS header, the seller can control whether the response is returned in JSON or XML format. If the Accept 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:

Input Parameters:
None.

HTTPS Request Headers and Input Parameters for the recommendationsSummary Call

HTTPS Headers:

Input Parameters:
None.

HTTPS Request Headers and Input Parameters for the recommendationItemIds Call

HTTPS Headers:

Input Parameters:

HTTPS Request Headers and Input Parameters for the itemRecommendations Call

HTTPS Headers:

Input Parameters:

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

recommendationsSummary Endpoint

https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/recommendationsSummary

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.

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).