Note: This initial version of the Listing Recommendation API is not available for testing in the Sandbox environment. |
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.
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.
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.
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.
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.
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.
For more information on Picture requirements enforcement, see the 2013 Spring Seller Update.
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.
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:
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:
0
or 1
in the add/revise/relist call.true
).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.
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:
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
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:
{
"type": "FnF",
"listingCount": "6"
},
{
"type": "Picture",
"listingCount": "47"
},
{
"type": "ItemSpecifics",
"listingCount": "6"
},
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
https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/140904540796/itemRecommendations?recommendationType=Picture
{
"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."
}
]
}
}
<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>
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.
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.
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.
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:
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:
Refer to the Call Reference for a list of calls in the Listing Recommendation API. The Call Reference includes the following information:
You can get more information about the eBay Listing Recommendation API at these locations:
Copyright © 2014–2016 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.