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:
- latestVersion: This call returns the current version of the Listing Recommendation API.
- recommendationsSummary: This call returns a count of listing recommendations for each listing recommendation type for all active listings owned by the seller.
- recommendationItemIds: This call returns a list of the seller's items that have one or more listing recommendations of a specific type.
- itemRecommendations: This call returns an array of active listing recommendations for a specific active or ended listing.
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:
- A Top-Rated Plus seal on their listing
- Improved search results for fixed-price listings
- Shipping discounts with the USPS Commercial Plus program
- A 20 percent discount on the final value fee
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:
- A handling time of 0 days (same-day shipping) or 1 day. If the seller has a listing with a handling time of more than 1 day, that seller may receive an 'eTRS' listing recommendation with a field name of 'shipsWithinDays'. If the seller receives this listing recommendation, the seller must revise the listing with a handling time of 0 days or 1 day through a Trading API Add/Revise/Relist call to qualify the listing as a Top-Rated Plus listing. To do this, the seller would include the DispatchTimeMax field in the call, and set its value to '0' or '1'.
- A return policy that states that the buyer has at least 14 days to return an unwanted item.
If the seller has a return policy that does not give the buyer at least 14 days to return an
item, that seller may receive an 'eTRS' listing recommendation with a field name of
'itemReturnedWithin'. If the seller receives this listing recommendation, the seller must
revise the listing in the following manner using the ReturnPolicy container
in a Trading API Add/Revise/Relist call to qualify the listing as a Top-Rated Plus listing:
- Include the ReturnPolicy.ReturnsAcceptedOption field in the call, and set its value to 'ReturnsAccepted'.
- Include the ReturnPolicy.ReturnsWithinOption field in the call, and set its value to a value that denotes a 14-day or longer (for example, 'Days_14') item return policy.
- Include the ReturnPolicy.RefundOption field in the call, and set its value to 'MoneyBack' or "MoneyBackOrExchange'.
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.
- New listings of branded items in new or manufacturer refurbished condition are required to include the item's brand/MPN or the product identifier (e.g., UPC, ISBN, or EAN) in select categories.
- You can find the select categories using the GetCategoryFeatures call.
- For single-variation listings using product identifiers, use the ProductListingDetails.EAN, ProductListingDetails.ISBN, or ProductListingDetails.UPC field. For a brand/MPN pair, use the ProductListingDetails.BrandMPN container and two ItemSpecifics.NameValueList containers; one for the brand and one for the MPN.
- For multi-variation listings, the product identifier (UPC, ISBN, or EAN) must be provided only at the variation level in the VariationProductListingDetails container. If a product identifier is provided in the Item.ProductListingDetails, the add/revise/relist call will fail.
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:
- All photos in your listing must be at least 500 pixels on the longest side.
- Photos cannot have any extra artwork, borders, or text.
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:
- binPrice: the recommended price for an item in a fixed-price listing or for the "Buy It Now" price in an auction listing. Upon getting a binPrice</strong recommendation, the seller may consider revising their listing with a price matching or closer to the recommended price.
- binPriceRange: the recommended price range for an item in a fixed-price listing or for the "Buy It Now" price in an auction listing. Upon getting a binPriceRange recommendation, the seller may consider revising their listing with a price within the recommended price range.
- listingType: this value is returned if the Listing Recommendation API is recommending a listing type (auction vs. fixed-price) for the item. Upon getting a ListingType recommendation, the seller may consider the recommended listing type the next time they list a similar item.
- startPrice: the recommended starting bid price for an item in an auction listing. Upon getting a startPrice recommendation, the seller may consider the recommended starting bid price the next time they list a similar item.
- startPriceRange: the recommended starting bid price range for an item in an auction listing. Upon getting a startPriceRange recommendation, the seller may consider the recommended starting bid price range the next time they list a similar item.
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:
- Missing keywords: the title is missing one or more keywords that would possibly help optimize the listing for Search and a quick sale/bidding. The recommended keyword(s) will be returned in the response.
- Missing Item Specifics: the title is missing one or more recommended Item Specifics that would possibly help optimize the listing for Search and a quick sale/bidding. The recommended Item Specific(s) will be returned in the response.
- Inaccurate keywords: the title contains one or more keywords that are inaccurately describing the listing. The offending keyword(s) will be returned in the response.
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:
- Offer same-day or 1-day handling time: the seller must set the value of the DispatchTimeMax field to
0
or1
in the add/revise/relist call. - Offer free shipping: one of the shipping service options specified through one of the ShippingServiceOptions containers in the add/revise/relist call should offer free shipping (FreeShipping field should be
true
).
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:
- AddFixedPriceItem: upon a successful call, the fixed-price item is created, and based on any listing recommendations, it will be at the seller's discretion to revise the item using a ReviseFixedPriceItem call.
- AddItem: upon a successful call, the item is created, and based on any listing recommendations, it will be at the seller's discretion to revise the item using a ReviseItem call.
- AddItems: upon a successful call, one or more items are created, and based on any listing recommendations for any of the newly created items, it will be at the seller's discretion to revise any of the items using one or more ReviseItem calls.
- RelistFixedPriceItem: upon a successful call, the fixed-price item is relisted, and based on any listing recommendations, it will be at the seller's discretion to revise the item using a ReviseFixedPriceItem call.
- RelistItem: upon a successful call, the item is relisted, and based on any listing recommendations, it will be at the seller's discretion to revise the item using a ReviseItem call.
- ReviseFixedPriceItem: upon a successful call, the active fixed-price item is revised, and based on any listing recommendations, it will be at the seller's discretion to revise the item again using a ReviseFixedPriceItem call.
- ReviseItem: upon a successful call, the active item is revised, and based on any listing recommendations, it will be at the seller's discretion to revise the item again using a ReviseItem call.
- VerifyAddFixedPriceItem: the seller should use this call to make sure that the fixed-price listing is meeting all requirements and quality standards before the item is actually listed in Production. Based on any listing recommendations, it will be at the seller's discretion to make any necessary changes to the listing before listing the item with an AddFixedPriceItem call.
- VerifyAddItem: the seller should use this call to make sure that the listing is meeting all requirements and quality standards before the item is actually listed in Production. Based on any listing recommendations, it will be at the seller's discretion to make any necessary changes to the listing before listing the item with an AddItem call.
- VerifyRelistItem: the seller should use this call to make sure that the item about to be relisted is meeting all requirements and quality standards before the item is actually relisted. Based on any listing recommendations, it will be at the seller's discretion to make any necessary changes to the listing before relisting the item with an RelistItem call.
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:
- All: listing recommendations of all types will be returned; this is the default value if no recommendationType parameter values are specified in the call.
- eTRS: listing recommendations related to Top-Rated Plus listing requirements will be returned.
- ItemSpecifics: listing recommendations related to required and recommended Item Specifics values will be returned.
- ProductIdentifier: listing recommendations related to mandated or recommended Product Identifiers will be returned.
- Picture: listing recommendations related to Picture quality requirements will be returned.
- Price: listing recommendations related to pricing and listing format will be returned.
- Title: listing recommendations related to keyword and Item Specifics in listing titles will be returned.
- FnF: listing recommendation to offer fast handling (same-day handling or handling time of 1 day) and/or a free shipping service option.
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:
- 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"
},
- 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. - 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."
}
]
}
} - 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:
- Invalid or missing eBay authorization token
- Invalid X-EBAY-GLOBAL-ID header value
- Invalid or missing recommendationType parameter value
- Invalid or missing pageNumber parameter value
- Invalid entriesPerPage parameter value (an integer value less than '1' or more than '5000'
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:
- Invalid call path
- Invalid or missing eBay authorization token
- Invalid or missing Item ID value in the call path
- A valid Item ID value was passed in the call path, but the item does not belong to the seller
- Invalid recommendationType parameter value(s)
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:
- Examples of each call request and prototypes of the response structure for each call
- Comprehensive list of input and output parameters for each call and descriptions of their meaning and behavior
- Call samples (request and response)
- Change history information for each call
Additional Resources
You can get more information about the eBay Listing Recommendation API at these locations: