Listing Recommendation API1.0.0
 

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 
recommendationType string Optional By default, listing recommendations of all types (value defaults to 'All') will be returned in the request if no recommendationType parameter values are used in the HTTPS request. However, the seller has the option to retrieve listing recommendations of a specific type, or types, by including these recommendationType values in the HTTPS request. If multiple values are used in the HTTPS request, these values are delimited with a comma. Possible values include the following:
  • All - by default, listing recommendations of all types will be returned in the request, but the seller is allowed to include the 'All' value in the HTTPS request;
  • 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 required or recommended Item Specifics 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 provides a recommended price and/or a recommended price range for auction and fixed-price listings. These price recommendation values are based on similar items that have recently sold on eBay. Along with pricing recommendations, a recommended listing format (auction vs. fixed-price) is also returned. This recommendation type is only supported on the US, UK, and DE sites;
  • Title - this recommendation type provides guidance on forming an effective listing title. The Listing Recommendation API will suggest that the listing title is missing valuable keywords, missing recommended Item Specifics, or has keywords that should not be there since it misrepresents the item. The keywords or Item Specifics are called out in the response. This recommendation type is 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.
(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
  • (added) New call.