eBay Trading APIVersion 1019

ListingRecommendationType

Type defining the Recommendation container(s) that are conditionally returned in all Add/Revise/Relist/Verify API calls. 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 use Fast 'N Free shipping.

One or more Recommendation containers can be returned for each listing.

Type that uses ListingRecommendationType:

Calls that use ListingRecommendationType:

Fields



Code ( string ) [0..1]
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.
See the Field Index to learn which calls use Code.

FieldName ( string ) [0..1]
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 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 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 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.

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:
  • BuyItNowPrice: the recommended price for an item in a fixed-price listing or for the "Buy It Now" price in an auction listing; this value will be shown in the Recommendation.Value field. Upon getting a BuyItNowPrice recommendation, the seller may consider revising their listing with a price matching or closer to the recommended price.
  • ListingType: this value is returned if a different listing type (auction vs. fixed-price) is being suggested 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.
Two other pricing recommendations, BuyItNowPriceRange and StartPriceRange, are supported in the Listing Recommendation API, but are not yet supported by the Trading API.

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 fast handling (same-day handling or handling time of 1 day), at least one free shipping service, or both. These two fieldName values are described below:
  • shipsWithinDays: this fieldName value is returned if the seller needs to implement fast handling (same-day handling or a handling time of 1 day). To implement fast handling, 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').


This FieldName field is always returned with each Recommendation container.
See the Field Index to learn which calls use FieldName.

Group ( string ) [0..1]
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'.
See the Field Index to learn which calls use Group.

Message ( string ) [0..1]
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/applicable.
See the Field Index to learn which calls use Message.

Metadata ( MetadataType ) [0..*]
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.

A Metadata container is returned for each price guidance parameter that is applicable/available for the pricing recommendation.
See the Field Index to learn which calls use Metadata.

Type ( string ) [0..1]
This value indicates the specific type of listing recommendation being provided to the seller. Possible values include the following:
  • eTRS - this recommendation type advises the seller that the listing is not meeting a specific Top-Rated listing requirement, such as same-day or 1-day handling or a 14-day (or longer) Money Back Return Policy;
  • ItemSpecifics - this recommendation type advises the seller that the listing is missing a required or recommended Item Specifics name/value pair;
  • Picture - this recommendation type advises the seller that a specific picture in the listing is not meeting a specific picture qualityrequirement;
  • 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 currently only supported on the US, UK, and DE sites;
  • Title - this recommendation type provides guidance on forming an effective listing title, and will suggest valuable keywords or recommended Item Specifics that the listing title is missing. This recommendation type will also call out keywords that do not accurately describe the item. The keywords or Item Specifics are called out in the response. 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 handling time of 1 day) and/or offer at least one free shipping service option.
See the Field Index to learn which calls use Type.

Value ( string ) [0..*]
The Value field 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 'BuyItNowPrice'); 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.
See the Field Index to learn which calls use Value.