Trading API
 

Listing Recommendation API User Guide

Note: This initial version of the Listing Recommendation API is not available for testing in the Sandbox environment.

API Overview

The Listing Recommendation API 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 Identifiers, picture quality requirements, pricing and/or listing format recommendations, recommended keywords and/or Item Specifics in a Title, and/or a recommendation to offer fast handling (same-day handling or handling time of 1 day) and/or a free shipping option in order to qualify the listing for a Fast 'N Free badge.

The following calls are available in the Listing Recommendation API. Each call requires the user's eBay authorization token in the header:

Refer to the Listing Recommendation API Call Reference for detailed information on each call, including required and optional header information, input parameters, output fields, and call samples.

Listing Recommendation Types

The Listing Recommendation types (classifications) are eTRS (eBay Top-Rated listing requirements), Item Specifics (mandatory and recommended Item Specifics), Product Identifiers (mandatory and recommended Product Identifiers), Picture (picture requirements in listings), Price (recommended prices and/or listing formats), Title (recommended keywords and Item Specifics to use in listing title), and Fast 'N Free (recommendation to offer Fast 'N Free shipping to entice prospective buyers).

The Listing Recommendation types are discussed further in the subsequent sections.

eTRS Recommendation Type - eBay Top-Rated Listing Requirements

The Top-Rated Seller requirements vary for each eBay site.

For each Top-Rated Plus listing a US seller creates, that seller will receive the following benefits:

Only US sellers that qualify as Top-Rated Sellers are eligible to have Top-Rated Plus listings. The two additional requirements of a Top-Rated Plus listing include the following:

For more information on Top-Rated Seller requirements and the Top-Rated Plus program, see the Becoming a Top-Rated Seller and qualifying for Top-Rated Plus Customer Support page.

For more information on setting a return policy for an item through the Trading API, see the Return Policy documentation in the AddItem call reference page.

ItemSpecifics Recommendation Type - Mandatory and Recommended Item Specifics

Item Specifics allow sellers to provide more details about their item in a structured format, allowing potential buyers to more easily find the item, and to help those buyers make an informed decision about purchasing that item.

Required and recommended Item Specifics for a listing will depend on the eBay Category that the item is listed under.

If the seller receives an 'ItemSpecifics' listing recommendation with a code value of 'MANDATORY_FIELD_VALUE_MISSING' or 'RECOMMENDED_FIELD_VALUE_MISSING', the seller will perform a ReviseItem/ReviseFixedPriceItem call, passing in the recommended Item Specific (with one or more values) through the ItemSpecifics.NameValueList container. If available, eBay will also return recommended Item Specific value(s) through the recommendation.value field.

ProductIdentifier Recommendation Type - Mandatory Product Identifiers

This type informs the seller of any listing which is missing the mandatory product identifier, such as Brand/MPN, UPC, ISBN or EAN.

Note: For complete information regarding the mandate, see the Requiring Product Identifiers Mandate section in the eBay Features Guide.

Picture Recommendation Type - Picture Requirements in Listings

This type is used by the seller to discover which listings are not adhering to picture quality requirements. The US picture quality requirements include the following:

If the seller receives a Picture listing recommendation, the fieldName value will be the URL of the image that needs to be brought up to picture quality standards. Noting the picture that requires updates, the seller will make the required picture update(s), and then perform a ReviseItem/ReviseFixedPriceItem call, passing in the URL of the image through the PictureURL field in the PictureDetails container.

Price Recommendation Type - Recommended Prices and Listing Format

This type is used by the seller to discover which listings are not optimally priced, and/or which items are in the wrong listing format (fixed-price vs. auction). This recommendation type is only supported by the US, UK, and DE sites.

There are actually five different pricing recommendations. These recommendations are summarized below:

If the seller receives any of the pricing recommendations, the recommended price or price range will appear in the response. If the 'ListingType' recommendation is returned, eBay will recommend the optimal listing type for the item.

Title Recommendation Type - Recommended Keywords and Item Specifics in Listing Title

This type is used by the seller to discover which listings have titles that are missing valuable keywords and Item Specifics, or that contain keywords that inaccurately describe the item, possibly leading to a bad buyer experience. This recommendation type is only supported by the US, UK, DE, and AU sites.

The three different title recommendations are summarized below:

Fast 'N Free Recommendation Type - Enabling Fast 'N Free Shipping

This type is used by the seller to discover which listings do not offer fast handling (same-day handling or handling time of 1 day) and/or a free shipping option. Listings that offer both fast handling and at least one free shipping option get the "Fast 'N Free" badge, which can increase sales. This recommendation type is supported by the US, UK, Germany, Australia, France, Italy, and Spain sites.

The two different Fast 'N Free recommendations are summarized below:

Listing Recommendation Use Cases

Retrieving listing recommendations through the Listing Recommendation API or through the Add/VerifyAdd/Revise/Relist Trading API calls can be useful to all sellers, regardless of their selling volume. The use cases for retrieving listing recommendations for single listings and multiple listings are covered in the next three sections.

Retrieving Listing Recommendations in Trading API for a Single Listing

The following 10 Trading API calls have the option of retrieving listing recommendations by including an IncludeRecommendations flag in the call request. The listing recommendations are returned in a ListingRecommendations container:

Retrieving Listing Recommendations in Listing Recommendation API for a Single Listing

Unlike the Trading API, where a seller can actually retrieve listing recommended for an item that is yet to be listed (using the VerifyAddItem or VerifyAddFixedPriceItem calls), the itemRecommendations call in the Listing Recommendation API can only retrieve listing recommendations for an existing item.

To retrieve listing recommendations for a specific listing, the seller makes the following HTTP GET call, substituting the actual eBay Item ID into the <eBayItemID> portion of the call path below:

https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/<eBayItemID>/itemRecommendations/

The call shown above will retrieve all listing recommendation types for the specified item. If the seller wanted to retrieve a specific listing recommendation type, such as eTRS, that seller can use a recommendationType parameter in the call and set its value to eTRS, as shown below:

https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/<eBayItemID>/itemRecommendations/?recommendationType=eTRS

The eight valid recommendationType parameter values are:

It is possible to specify multiple recommendationType parameter values in the request. A comma is used as the delimiter if more than one value is used. An example of this syntax is shown below:

https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/<eBayItemID>/itemRecommendations/?recommendationType=eTRS,Picture

Using the Listing Recommendation API to Discover Multiple Items with Listing Recommendations

To ultimately discover and revise listings with listing recommendations, high-volume sellers will want to use three calls of the Listing Recommendation API, and ultimately, a ReviseItem Trading API call to revise the listing with the corresponding listing recommendation(s). This call flow is described below:

  1. First, the seller makes a recommendationsSummary call. In the response to this call, the seller gets a summary of the work that must be done to improve the quality of their listings, in regards to the returned listing recommendation types. It could be that all of the seller's listings are meeting eTRS and Picture quality requirements, and each listing is using the required and recommended Item Specifics, but eBay is recommending that some listings could be improved by incorporating the use of Fast 'N Free shipping. In this case, the JSON response would look something like this:

    {
      "type": "FnF",
      "listingCount": "6"
    },

    Or, maybe the seller's listings are meeting eTRS requirements, but eBay is telling the seller that some listings have pictures not meeting Picture quality requirements and other listings are missing recommended Item Specifics. In this case, the JSON response would look something like this:

    {
      "type": "Picture",
      "listingCount": "47"
    },

    {
      "type": "ItemSpecifics",
      "listingCount": "6"
    },

  2. Next in the flow, the seller will make one recommendationItemIds call for each Listing Recommendation type that was returned in the recommendationsSummary call. If Picture listing recommendations were returned in the recommendationsSummary call, the seller would want to pass in a value of Picture into the recommendationType parameter in the request. And based on the total number of listings with Picture listing recommendations, the seller would also want include and set values for the pageNumber and entriesPerPage parameters in the requests. If 47 of the seller's listings have Picture listing recommendations, the recommendationItemIds call may look something like this:

    https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/recommendationItemIds?recommendationType=Picture&pageNumber=1&entriesPerPage=50

    By including the entriesPerPage parameter and setting its value to '50', the Item IDs for all 47 listings will be returned in one recommendationItemIds call.
  3. After retrieving the Item IDs with listing recommendations, the seller will now make one itemRecommendations call for each of those items, passing in the Item ID as part of the path, and including the recommendationType parameter in the request and setting the appropriate value for this parameter. The request might look something like this:

    https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/140904540796/itemRecommendations?recommendationType=Picture

    The JSON response to this call might look like the following:

    {
        "itemId": "140904540796",
        "recommendation":[
        {
          "type": "Picture",
          "group": "PICTURE_RESOLUTION",
          "fieldName": "http://i.ebayimg.com/TJPGRPNG~~60_12.JPG",
          "code": "RECOMMENDED_STANDARDS_NOT_MET",
          "message": "To improve your chances of selling this item, upload a larger photo that is at least 500 pixels on the longest side. Later this year, all listings will require this, so please update all your photos to this size at a minimum. Not doing so will violate our policy on photos and could result in a listing being removed."
        }
       ]
      }
    }
  4. If a seller received a itemRecommendations response like the one above, first that seller would want to edit the image specified in fieldName field. In this case, it's a picture resolution issue, which means that the longest side of the image is less than 500 pixels. Once the longest side of the image stored at the specified URL is made to be 500 pixels or more, that seller would want to make a ReviseItem Trading API call, passing in the corresponding Item ID in the ItemID field of the call, and the corresponding image URL in the PictureDetails.PictureURL field of the call. This ReviseItem call (in XML format) might look like the following:

    <ReviseItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
      <WarningLevel>High</WarningLevel>
      <Item>
        <ItemID>140904540796</ItemID>
        <PictureDetails>
          <PictureURL>http://i.ebayimg.com/TJPGRPNG~~60_12.JPG</PictureURL>
        </PictureDetails>
      </Item>
      <RequesterCredentials>
        <eBayAuthToken>*****</eBayAuthToken>
      </RequesterCredentials>
    </ReviseItemRequest>

Using the Listing Recommendation API Calls

The subsequent sections give a brief overview of each Listing Recommendation API call. For more detailed information on each call's input parameters and returned fields, see the corresponding call's Call Reference page.

Using the latestVersion Call

The latestVersion call returns the current version of the Listing Recommendation API.

The seller's eBay authorization token is a required HTTP header and there are no required or optional parameters in the call request.

The only returned field is the version number of the Listing Recommendation API.

As long as the seller's eBay authorization token is valid, this call should be successful.

Using the recommendationsSummary Call

The recommendationsSummary call returns a count of listing recommendations for each listing recommendation type for all active listings owned by the seller.

The seller's eBay authorization token is a required HTTP header and the eBay site ID is an optional HTTP header. There are no required or optional parameters in the call request.

Applicable listing types, and the number of the seller's listings that have one or more listing recommendations of this type, are returned for each eBay site on which the seller has listings.

As long as the seller's eBay authorization token is valid, this call should be successful. If no listing recommendations exist for any of the seller's listings, an empty recommendationsSummaryResponse container should be returned.

Using the recommendationItemIds Call

The recommendationItemIds call returns a list of the seller's items that have one or more listing recommendations of a specific type.

The seller's eBay authorization token is a required HTTP header. The global ID of the eBay site (such as EBAY-US) is an optional HTTP header, and defaults to US if it is not specified. The recommendationType parameter is required in the call request. Pagination parameters are also used in the request. The pageNumber parameter is required and controls which page of results (Item IDs) is returned in the request. The entriesPerPage parameter is optional and controls how many Item IDs are returned per page of results.

An array of Item IDs are returned for the specified eBay site and listing recommendation type. A pagination container is also returned and gives details on which page of results is currently being shown, how many Item IDs are shown on each page of results, the total number of results pages, and the total numbers of Item IDs that match the input criteria.

With this call, the following errors are possible:

Using the itemRecommendations Call

The itemRecommendations call returns an array of active listing recommendations for a specific active or ended listing.

The seller's eBay authorization token is a required HTTP header. The listing's Item ID value is required as part of call path. The recommendationType parameter is optional in the call request. If the recommendationType parameter is omitted, listing recommendations of all types are returned in the response. The seller also has the option of returning more than one listing recommendation type by passing in multiple values (delimited by commas) in the recommendationType parameter (for example, ?recommendationType=eTRS,Picture.

A recommendation container is returned for each of the specified item's listing recommendations. Each recommendation container includes the listing recommendation's type and provides a message to the seller on how the listing can be improved or brought up to standard in regards to top-rated seller/listing requirements, mandated or recommended Item Specifics, mandated or recommended Product Identifiers, picture quality requirements, pricing and/or listing format recommendations, recommended keywords and/or Item Specifics in a Title, and/or a recommendation to offer buyers Fast 'N Free shipping. If no listing recommendations of the specified type(s) exist for any of the seller's listings, an empty itemRecommendationsResponse container should be returned.

With this call, the following errors are possible:

Working with the Listing Recommendation API

API Reference

Refer to the Call Reference for a list of calls in the Listing Recommendation API. The Call Reference includes the following information:

Back to top

Additional Resources

You can get more information about the eBay Listing Recommendation API at these locations: