itemRecommendations
Note: This initial version of the Listing Recommendation API is not available for
testing in the Sandbox environment.
|
A seller can use this call to return an array of listing recommendations for a
specific active or ended listing. It is up to the seller about whether to retrieve
listing recommendations of all types, or to retrieve listing recommendations of a specific
type, or types.
If there are no listing recommendations available for the specified listing, an empty (no
data) itemRecommendationsResponse container is returned. A seller can only
request listing recommendations for their own listings. If the seller passes in an Item ID
value for a listing that does not belong to him/her, an error is returned.
Back to top
itemRecommendations Input
The seller's itemId value is required as part of the path for this call
(see the actual Item ID value in sample call below).
An example of a itemRecommendations HTTPS request (with the single
recommendationType query parameter) is shown below. To learn more about the
recommendationType query parameter and its possible values, click its name in the
sample call (or scroll down to find it in the table).
See also Samples.
https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/140904540796/itemRecommendations/?recommendationType=eTRS,Picture
Back to top
Argument |
Type |
Occurrence |
Meaning |
Call-Specific Input Fields Â
|
(No Standard Input fields) |
itemRecommendations Output
The XML sample response in the box below lists all parameters that might be returned in the response. To learn more about an individual parameter and its possible values, click its name in the box (or scroll down to find it in the table below the box).
See also Samples.
<?xml version="1.0" encoding="utf-8"?>
<itemRecommendationsResponse xmlns="http://www.ebay.com/marketplace/listing/v1/service">
<!-- Call-Specific Output Fields -->
<itemId>string</itemId>
<recommendation>
<code>string</code>
<fieldName>string</fieldName>
<group>string</group>
<message>string</message>
<recommendationData>
<appliesTo>string</appliesTo>
<currency>string</currency>
<maxRecommendedValue>string</maxRecommendedValue>
<minRecommendedValue>string</minRecommendedValue>
<similarItems>string</similarItems>
<!-- ... more similarItems fields possible here ... -->
</recommendationData>
<type>string</type>
<value>string</value>
<!-- ... more value fields possible here ... -->
</recommendation>
<!-- ... more recommendation nodes possible here ... -->
<!-- (No Standard Output fields) -->
</itemRecommendationsResponse>
Return Value |
Type |
Occurrence |
Meaning |
Call-Specific Output Fields Â
|
itemId
|
string |
Always |
The unique identifier of the seller's item. This is the same Item ID that is passed in the
HTTPS request. All recommendations returned in the itemRecommendations
response will pertain to this item.
|
recommendation
|
container |
Conditionally |
Container consisting of one listing recommendation for the specified item. The type of recommendations that are returned in recommendation containers will be determined by the recommendationType parameter(s) that are passed in to the itemRecommendations HTTPS request. Each
recommendation container provides a message to the seller on how a listing
can be improved or brought up to standard in regards to top-rated seller/listing requirements, mandated or recommended Item Specifics, picture quality requirements, pricing and/or listing format recommendations, recommended keywords and/or Item Specifics in a Title, and/or a recommendation to enable the listing with Fast 'N Free shipping.
Zero or more recommendation containers can be returned in the response. If
no listing recommendations are available for the specified listing, no
recommendation containers will be returned.
|
recommendation.code
|
string |
Conditionally |
This code value provides a generic, "human-friendly" message summarizing what is wrong with the listing, or how it can be improved. These values include:
- FIELD_VALUE_INCORRECT
- FIELD_VALUE_RECOMMENDATION
- MANDATED_FIELD_VALUE_MISSING
- MANDATORY_STANDARDS_NOT_MET
- RECOMMENDED_FIELD_VALUE_MISSING
- RECOMMENDED_FIELD_VALUE_TO_REMOVE
- RECOMMENDED_STANDARDS_NOT_MET
This field is always returned with each recommendation container.
|
recommendation.fieldName
|
string |
Conditionally |
The fieldName value will vary based on the recommendation type. The fieldName values for each recommendation type are summarized below.
For eTRS listing recommendations, the fieldName value will
indicate the specific Trading API field that the seller needs to update to bring the listing
up to top-rated listing standards. For example, if the listing recommendation.type
value is 'eTRS' and the recommendation.group value is 'SHIPPING', the
fieldName value may be 'DispatchTimeMax'. If the seller is returned a
listing recommendation like this, it would most likely indicate that the seller must reduce
the handling time (DispatchTimeMax value in Trading API) in the listing to '0' (same-day shipping) or '1' (one-day handling time) in order for the listing to qualify
as a top-rated listing and receive a Top Rated Plus seal in View Item and Search Results
pages.
For an ItemSpecifics listing recommendation, the fieldName
value will be the name of the recommended Item Specific. If the seller gets a
ItemSpecifics listing recommendation, 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.
For a ProductIdentifier listing recommendation, the fieldName
value will be the name of the mandated/recommended Product Identifier. If the seller gets a
ProductIdentifier listing recommendation, the seller will perform a
ReviseItem/ReviseFixedPriceItem call, passing in the
recommended Product Identifier type and value through the
ProductListingDetails container. If available, eBay will also
return the actual Product ID value in the recommendation.value
field.
For a Picture listing recommendation, the fieldName value
will be the URL of the image that needs to be brought up to picture quality standards. If the
seller gets a Picture listing recommendation for this image in the listing,
the seller will need to make the required picture quality update, and then perform a
ReviseItem/ReviseFixedPriceItem call, passing in the
URL of the image through the PictureURL field in the
PictureDetails container.
For a Price listing recommendation, the fieldName value will be one of the following:
- binPrice: the recommended price for an item in a fixed-price listing or the "Buy It Now" price for an auction listing; this value will be shown in the recommendation.value field. 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 the "Buy It Now" price range for an auction listing; this price range will be shown in the recommendation.minRecommendedValue and recommendation.maxRecommendedValue fields. 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; this value will be shown in the recommendation.value field. 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; this price range will be shown in the recommendation.minRecommendedValue and recommendation.maxRecommendedValue fields. 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 gets a Picture listing recommendation for this image in the listing,
the seller will need to make the required picture quality update, and then perform a
ReviseItem/ReviseFixedPriceItem call, passing in the
URL of the image through the PictureURL field in the
PictureDetails container.
For a Title listing recommendation, the fieldName value will be 'Title' for any of the three use cases - missing keywords, missing Item Specifics, or inaccurate keywords. Upon getting a Title recommendation, the seller may consider the Title recommendation (adding keywords, adding Item Specifics, removing inaccurate keywords) the next time they list a similar item.
For an FnF listing recommendation, either one or two recommendation containers will be returned, based on whether a listing needs expedited shipping, free shipping, or both. These two fieldName values are described below:
- shipsWithinDays: this fieldName value is returned if the seller needs to implement expedited shipping (same-day shipping or a handling time of 1 day). To implement expedited shipping, the seller will perform a ReviseItem/ReviseFixedPriceItem call, passing a value of '0' or '1' into the DispatchTimeMax field.
- shippingServiceCost: this fieldName value is returned if the seller needs to offer a free shipping service option in the listing. To add a free shipping service option, the seller will perform a ReviseItem/ReviseFixedPriceItem call, passing in one or more ShippingDetails.ShippingServiceOptions containers where the shipping service is free (ShippingServiceOptions.FreeShipping boolean value set to 'true').
|
recommendation.group
|
string |
Conditionally |
This value indicates the group that a specific listing recommendation belongs to. There may
be multiple groups for each listing recommendation type. For example, two groups of the eTRS
listing recommendation type are 'SHIPPING' and 'RETURNS'.
This field is always returned with each recommendation container.
|
recommendation.message
|
string |
Conditionally |
This textual message is the detailed description of a specific action that a seller can take to improve the quality of the listing, or bring it up to Picture or eTRS standards. For some recommendations, the fields may be revised on an active listing
through a ReviseItem or ReviseFixedPriceItem call of the Trading API. For other recommendations, it may not be possible to revise the fields on an active listing.
This field is returned in the recommendation container when available.
|
recommendation.recommendationData
|
string |
Conditionally |
This container contains price guidance information, which includes the minimum and maximum recommended prices for the item, which are based on recent sales of similar items. This container is only returned for price recommendations and when the pricing data is available.
|
recommendation.recommendationData.appliesTo
|
string |
Conditionally |
This value indicates the listing type to which the recommended prices apply. Applicable values are 'Auction' and 'FixedPrice'.
|
recommendation.recommendationData.currency
|
string |
Conditionally |
This value indicates the currency being used for the minRecommendedValue and maxRecommendedValue dollar values.
|
recommendation.recommendationData.maxRecommendedValue
|
string |
Conditionally |
This container contains price guidance information, which includes the minimum and maximum recommended prices for the item, which are based on recent sales of similar items. This container is only returned for price recommendations and when the pricing data is available.
|
recommendation.recommendationData.minRecommendedValue
|
string |
Conditionally |
This container contains price guidance information, which includes the minimum and maximum recommended prices for the item, which are based on recent sales of similar items. This container is only returned for price recommendations and when the pricing data is available.
|
recommendation.recommendationData.similarItems
|
container |
Conditionally |
This container holds an array of eBay Item ID values that correspond to sold eBay items that are similar to the item that has a pricing recommendation. The minRecommendedValue and maxRecommendedValue values are based on the sell prices of the items in this container.
|
recommendation.type
|
string |
Conditionally |
This value indicates the specific type of listing recommendation. Possible values include the
following:
- eTRS - this recommendation type advises the seller that the listing is not meeting a specific top-rated listing requirement;
- ItemSpecifics - this recommendation type advises the seller that the listing is missing a recommended Item Specific value;
- ProductIdentifier - this recommendation type advises the seller that the listing is missing the product identifier, such as Brand/MPN, UPC, ISBN or EAN;
- Picture - this recommendation type advises the seller that a specific picture in the listing is not meeting a specific picture quality requirement;
- Price - this recommendation type advises the seller that a different sale price for a fixed-price item or a different starting bid price for an auction item might improve the seller's chance of selling the item. Along with pricing recommendations, this recommendation type may also return a recommendation to switch listing types (fixed-price to auction, or vice versa). This recommendation type is currently only supported on the US, UK, and DE sites;
- Title - this recommendation type advises the seller that a listing may be improved if valuable keywords or Item Specifics are added to the Title. This type will also advise the seller if the Title is using inaccurate keywords, or keywords that may lead the buyer astray and possibly cause a bad buying experience. This recommendation type is currently only supported on the US, UK, DE, and AU sites; and
- FnF - this recommendation type advises the seller to offer expedited shipping for the item (same-day shipping or a handling time of 1 day) and/or offer at least one free shipping service option. This recommendation type is only supported by the US, UK, Germany, Australia, France, Italy, and Spain sites.
This field is always returned with each recommendation container.
|
recommendation.value
|
string |
Conditionally |
This value is only applicable for ItemSpecifics, Pricing, and Title listing recommendation types, and it is only returned for these recommendation types.
For the ItemSpecifics recommendation type, the value
in the value field is a recommended value for the recommended Item Specific
name found in the recommendation.fieldName field. Each Item Specific name
can have more than one recommended value, so it is possible to have multiple
recommendation.value fields for that recommendation. It is also possible that a
recommended Item Specific name will have no recommended values, hence no
recommendation.fieldName values are returned.
For the Pricing recommendation type, the value
in the value field is either:
- a recommended value for the starting bid price (if recommendation.fieldName value is 'StartPrice');
- a recommended value for a fixed-price item (if recommendation.fieldName value is 'binPrice'); or
- a recommended value for the listing type (if recommendation.fieldName value is 'ListingType').
For the Title recommendation type, the value
in the value field is either:
- a recommended keyword to include in the listing Title (if recommendation.code value is 'RECOMMENDED_FIELD_VALUE_MISSING');
- a recommended keyword to remove (to maintain accuracy) in the listing Title (if recommendation.code value is 'RECOMMENDED_FIELD_VALUE_TO_REMOVE');
- a recommended Item Specific to include in the listing Title (if recommendation.code value is 'FIELD_VALUE_RECOMMENDATION');
Each Title recommendation can have more than one keyword or Item Specific value, so it is possible to have multiple
recommendation.value fields for that recommendation.
|
(No Standard Output fields) |
Back to top
itemRecommendations Samples
Sample: Basic Call
This call retrieves listing recommendations for an eBay listing.
Description
The following call retrieves all listing recommendations of all types for the eBay
listing with an Item ID of '221209137374'. The seller making this call must own this listing
or an error will be returned.
Input
The following itemRecommendations HTTPS GET call retrieves all listing
recommendations of all types for eBay Item# 221209137374.
https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/221209137374/itemRecommendations
Output
The JSON call response include three listing recommendations.
The 'ItemsSpecifics' listing
recommendation is telling the seller that 'Color' is a recommended Item Specifics for the
item's category. For this 'ItemSpecifics' listing recommendation, there were no suggested
values for the 'Color' Item Specifics. To improve the listing based on this listing
recommendation, the seller would perform a ReviseItem/ReviseFixedPriceItem
call, passing in the 'Color' Item Specific and the actual color of the item through the
ItemSpecifics.NameValueList container.
The 'Picture' listing
recommendation is telling the seller that the picture stored at the URL specified in the
fieldName field is not meeting the eBay Picture Resolution standard, which
requires that pictures in listing are at least 500 pixels on the longest side.
To improve the listing based on this listing recommendation, the seller would upload a revised
picture (at least 500 pixels on the longest side) to the URL specified in the
fieldName field, and then perform a ReviseItem/
ReviseFixedPriceItem call, passing in the URL of the image through the PictureURL
field in the PictureDetails container.
The two 'FnF' listing
recommendations are suggesting that the seller offer same-day or 1-day handling and offer at least one free shipping service option, so that the listing will qualify as a Fast 'N Free listing. To improve the listing based on this listing
recommendation, the seller would perform a ReviseItem/ReviseFixedPriceItem call, including the Item.DispatchTimeMax field in the request and setting its value to '0' or '1', and setting the FreeShipping boolean value to 'True' in at least one ShippingServiceOptions container.
{
"itemId": 221209137374,
"Recommendation":
{
"type": "ItemSpecifics",
"group": "ITEM_SPECIFICS",
"fieldName": "Color",
"code": "RECOMMENDED_FIELD_VALUE_MISSING"
},
{
"type": "Picture",
"group": "PICTURE_RESOLUTION",
"fieldName": "http://i.ebayimg.com/00/s/MTg2WDMwMA==/z/OMMAAOxyZw5RaEq-/$T2eC16R,!yUE9s6NFIJdBR,Eq95-Sg~~60_1.JPG?set_id=8800004005",
"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."
},
{
"type": "FnF",
"group": "SHIPPING",
"fieldName": "ShipsWithinDays",
"code": "FIELD_VALUE_RECOMMENDATION",
"message": ": Offer same day or 1-day handling time."
},
{
"type": "FnF",
"group": "SHIPPING",
"fieldName": "ShippingServiceCost",
"code": "FIELD_VALUE_RECOMMENDATION",
"message": ": Offer free shipping."
}
]
}
Back to top
itemRecommendations Change History
Version |
Description |
1.0.0 2015-07-10 |
- (added) Added ProductIdentifier to recommendationType.
|
1.0.0 2013-04-12 |
|