eBay Trading API
|
Examines potential item data that a seller has specified and returns recommended changes or opportunities for improvement. The types of recommendations returned for a given item can be configured by choosing one or more recommendation engines in the request. This call supports batch requests. That is, you can retrieve recommendations for multiple items at once.
See:
Introduction to Pictures in Item Listings
GetItemRecommendations
Getting Recommendations to Improve a Listing
Working with Custom Item Specifics
| Output Detail Controls Samples Change History Top Errors for GetItemRecommendations User Notes |
The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).
See also Samples.
See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.
The XML prototype may be missing some XML fields and attributes. This is a documentation limitation only (see Limitations of This Document).
<?xml version="1.0" encoding="utf-8"?>
<GetItemRecommendationsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
<!-- Standard Input Fields -->
<ErrorLanguage> string </ErrorLanguage>
<MessageID> string </MessageID>
<Version> string </Version>
<WarningLevel> WarningLevelCodeType </WarningLevel>
<!-- Call-specific Input Fields -->
<GetRecommendationsRequestContainer> GetRecommendationsRequestContainerType
<CorrelationID> string </CorrelationID>
<DeletedField> string </DeletedField>
<!-- ... more DeletedField nodes here ... -->
<Item> ItemType
<ApplicationData> string </ApplicationData>
<ApplyShippingDiscount> boolean </ApplyShippingDiscount>
<AttributeSetArray> AttributeSetArrayType
<AttributeSet attributeSetID="int" attributeSetVersion="string"> AttributeSetType
<Attribute attributeID="int"> AttributeType
<Value> ValType
<ValueID> int </ValueID>
<ValueLiteral> string </ValueLiteral>
</Value>
<!-- ... more Value nodes here ... -->
</Attribute>
<!-- ... more Attribute nodes here ... -->
</AttributeSet>
<!-- ... more AttributeSet nodes here ... -->
</AttributeSetArray>
<AutoPay> boolean </AutoPay>
<BestOfferDetails> BestOfferDetailsType
<BestOfferEnabled> boolean </BestOfferEnabled>
</BestOfferDetails>
<BuyerRequirementDetails> BuyerRequirementDetailsType
<LinkedPayPalAccount> boolean </LinkedPayPalAccount>
<MaximumBuyerPolicyViolations> MaximumBuyerPolicyViolationsType
<Count> int </Count>
<Period> PeriodCodeType </Period>
</MaximumBuyerPolicyViolations>
<MaximumItemRequirements> MaximumItemRequirementsType
<MaximumItemCount> int </MaximumItemCount>
<MinimumFeedbackScore> int </MinimumFeedbackScore>
</MaximumItemRequirements>
<MaximumUnpaidItemStrikesInfo> MaximumUnpaidItemStrikesInfoType
<Count> int </Count>
<Period> PeriodCodeType </Period>
</MaximumUnpaidItemStrikesInfo>
<MinimumFeedbackScore> int </MinimumFeedbackScore>
<ShipToRegistrationCountry> boolean </ShipToRegistrationCountry>
<VerifiedUserRequirements> VerifiedUserRequirementsType
<MinimumFeedbackScore> int </MinimumFeedbackScore>
<VerifiedUser> boolean </VerifiedUser>
</VerifiedUserRequirements>
<ZeroFeedbackScore> boolean </ZeroFeedbackScore>
</BuyerRequirementDetails>
<BuyerResponsibleForShipping> boolean </BuyerResponsibleForShipping>
<BuyItNowPrice> AmountType (double) </BuyItNowPrice>
<CategoryBasedAttributesPrefill> boolean </CategoryBasedAttributesPrefill>
<CategoryMappingAllowed> boolean </CategoryMappingAllowed>
<Charity> CharityType
<CharityID> string </CharityID>
<CharityNumber> int </CharityNumber>
<DonationPercent> float </DonationPercent>
</Charity>
<Currency> CurrencyCodeType </Currency>
<Description> string </Description>
<DisableBuyerRequirements> boolean </DisableBuyerRequirements>
<DispatchTimeMax> int </DispatchTimeMax>
<ExternalProductID> ExternalProductIDType
<ReturnSearchResultOnDuplicates> boolean </ReturnSearchResultOnDuplicates>
<Type> ExternalProductCodeType </Type>
<Value> string </Value>
</ExternalProductID>
<GetItFast> boolean </GetItFast>
<GiftIcon> int </GiftIcon>
<GiftServices> GiftServicesCodeType </GiftServices>
<!-- ... more GiftServices nodes here ... -->
<HitCounter> HitCounterCodeType </HitCounter>
<ItemID> ItemIDType (string) </ItemID>
<ItemSpecifics> NameValueListArrayType
</ItemSpecifics>
<LimitedWarrantyEligible> boolean </LimitedWarrantyEligible>
<ListingDesigner> ListingDesignerType
<LayoutID> int </LayoutID>
<OptimalPictureSize> boolean </OptimalPictureSize>
<ThemeID> int </ThemeID>
</ListingDesigner>
<ListingDetails> ListingDetailsType
<LocalListingDistance> string </LocalListingDistance>
<MinimumBestOfferMessage> string </MinimumBestOfferMessage>
<MinimumBestOfferPrice> AmountType (double) </MinimumBestOfferPrice>
</ListingDetails>
<ListingDuration> token </ListingDuration>
<ListingEnhancement> ListingEnhancementsCodeType </ListingEnhancement>
<!-- ... more ListingEnhancement nodes here ... -->
<ListingType> ListingTypeCodeType </ListingType>
<Location> string </Location>
<LookupAttributeArray> LookupAttributeArrayType
<LookupAttribute> LookupAttributeType
<Name> string </Name>
<Value> string </Value>
</LookupAttribute>
<!-- ... more LookupAttribute nodes here ... -->
</LookupAttributeArray>
<LotSize> int </LotSize>
<MotorsGermanySearchable> boolean </MotorsGermanySearchable>
<NowAndNew> boolean </NowAndNew>
<PaymentDetails> PaymentDetailsType
<DaysToFullPayment> int </DaysToFullPayment>
<HoursToDeposit> int </HoursToDeposit>
</PaymentDetails>
<PaymentMethods> BuyerPaymentMethodCodeType </PaymentMethods>
<!-- ... more PaymentMethods nodes here ... -->
<PayPalEmailAddress> string </PayPalEmailAddress>
<PictureDetails> PictureDetailsType
<GalleryType> GalleryTypeCodeType </GalleryType>
<GalleryURL> anyURI </GalleryURL>
<PhotoDisplay> PhotoDisplayCodeType </PhotoDisplay>
<PictureURL> anyURI </PictureURL>
<!-- ... more PictureURL nodes here ... -->
</PictureDetails>
<PostalCode> string </PostalCode>
<PrimaryCategory> CategoryType
<CategoryID> string </CategoryID>
</PrimaryCategory>
<PrivateListing> boolean </PrivateListing>
<PrivateNotes> string </PrivateNotes>
<ProductListingDetails> ProductListingDetailsType
<IncludePrefilledItemInformation> boolean </IncludePrefilledItemInformation>
<IncludeStockPhotoURL> boolean </IncludeStockPhotoURL>
<ProductID> string </ProductID>
<UseStockPhotoURLAsGallery> boolean </UseStockPhotoURLAsGallery>
</ProductListingDetails>
<Quantity> int </Quantity>
<RelistLink> boolean </RelistLink>
<ReservePrice> AmountType (double) </ReservePrice>
<ReturnPolicy> ReturnPolicyType
<Description> string </Description>
<EAN> string </EAN>
<RefundOption> token </RefundOption>
<ReturnsAcceptedOption> token </ReturnsAcceptedOption>
<ReturnsWithinOption> token </ReturnsWithinOption>
<ShippingCostPaidByOption> token </ShippingCostPaidByOption>
<WarrantyDurationOption> token </WarrantyDurationOption>
<WarrantyOfferedOption> token </WarrantyOfferedOption>
<WarrantyTypeOption> token </WarrantyTypeOption>
</ReturnPolicy>
<ScheduleTime> dateTime </ScheduleTime>
<SecondaryCategory> CategoryType
<CategoryID> string </CategoryID>
</SecondaryCategory>
<SellerInventoryID> string </SellerInventoryID>
<ShippingDetails> ShippingDetailsType
<CalculatedShippingRate> CalculatedShippingRateType
<OriginatingPostalCode> string </OriginatingPostalCode>
<PackageDepth> MeasureType (decimal) </PackageDepth>
<PackageLength> MeasureType (decimal) </PackageLength>
<PackageWidth> MeasureType (decimal) </PackageWidth>
<PackagingHandlingCosts> AmountType (double) </PackagingHandlingCosts>
<ShippingIrregular> boolean </ShippingIrregular>
<ShippingPackage> ShippingPackageCodeType </ShippingPackage>
<WeightMajor> MeasureType (decimal) </WeightMajor>
<WeightMinor> MeasureType (decimal) </WeightMinor>
</CalculatedShippingRate>
<InsuranceFee> AmountType (double) </InsuranceFee>
<InsuranceOption> InsuranceOptionCodeType </InsuranceOption>
<InternationalShippingServiceOption> InternationalShippingServiceOptionsType
<ShippingService> token </ShippingService>
<ShippingServiceAdditionalCost> AmountType (double) </ShippingServiceAdditionalCost>
<ShippingServiceCost> AmountType (double) </ShippingServiceCost>
<ShippingServicePriority> int </ShippingServicePriority>
<ShipToLocation> string </ShipToLocation>
<!-- ... more ShipToLocation nodes here ... -->
</InternationalShippingServiceOption>
<!-- ... more InternationalShippingServiceOption nodes here ... -->
<PaymentInstructions> string </PaymentInstructions>
<SalesTax> SalesTaxType
<SalesTaxPercent> float </SalesTaxPercent>
<SalesTaxState> string </SalesTaxState>
<ShippingIncludedInTax> boolean </ShippingIncludedInTax>
</SalesTax>
<ShippingServiceOptions> ShippingServiceOptionsType
<ShippingService> token </ShippingService>
<ShippingServiceAdditionalCost> AmountType (double) </ShippingServiceAdditionalCost>
<ShippingServiceCost> AmountType (double) </ShippingServiceCost>
<ShippingServicePriority> int </ShippingServicePriority>
<ShippingSurcharge> AmountType (double) </ShippingSurcharge>
</ShippingServiceOptions>
<!-- ... more ShippingServiceOptions nodes here ... -->
<ShippingType> ShippingTypeCodeType </ShippingType>
</ShippingDetails>
<ShippingTermsInDescription> boolean </ShippingTermsInDescription>
<ShipToLocations> string </ShipToLocations>
<!-- ... more ShipToLocations nodes here ... -->
<Site> SiteCodeType </Site>
<SKU> SKUType (string) </SKU>
<StartPrice> AmountType (double) </StartPrice>
<Storefront> StorefrontType
<StoreCategory2ID> long </StoreCategory2ID>
<StoreCategoryID> long </StoreCategoryID>
</Storefront>
<SubTitle> string </SubTitle>
<ThirdPartyCheckout> boolean </ThirdPartyCheckout>
<ThirdPartyCheckoutIntegration> boolean </ThirdPartyCheckoutIntegration>
<Title> string </Title>
<UseTaxTable> boolean </UseTaxTable>
<VATDetails> VATDetailsType
<BusinessSeller> boolean </BusinessSeller>
<RestrictedToBusiness> boolean </RestrictedToBusiness>
<VATPercent> float </VATPercent>
</VATDetails>
</Item>
<ListingFlow> ListingFlowCodeType </ListingFlow>
<Query> string </Query>
<RecommendationEngine> RecommendationEngineCodeType </RecommendationEngine>
<!-- ... more RecommendationEngine nodes here ... -->
</GetRecommendationsRequestContainer>
<!-- ... more GetRecommendationsRequestContainer nodes here ... -->
</GetItemRecommendationsRequest>
| Argument | Type | Reqd? | Meaning |
|---|---|---|---|
| Standard Input Fields [Jump to call-specific fields] | |||
| ErrorLanguage | string | Optional |
Use ErrorLanguage to return error strings for the call in a different language from the language commonly associated with the site that the requesting user is registered with. Specify the standard RFC 3066 language identification tag (e.g., en_US). ID--- country ----- ----- de_AT Austria de_CH Switzerland de_DE Germany en_AU Australia en_CA Canada en_GB United Kingdom en_SG Singapore en_US United States es_ES Spain fr_BE Belgium (French) fr_CA Canada (French) fr_FR France it_IT Italy nl_BE Belgium (Dutch) nl_NL Netherlands zh_CN China en_IN India en_IE Ireland zh_HK Hong Kong See Tags for the Identification of Languages. |
| MessageID | string | Optional |
In most cases, all calls support a MessageID element in the request and a CorrelationID element in the response. If you pass a message ID in a request, we will return the same value in CorrelationID in the response. You can use this for tracking that a response is returned for every request and to match particular responses to particular requests. If you do not pass MessageID in the request, CorrelationID is not returned. Note: GetCategories, GetAttributesCS, GetCategory2CS, GetAttributesXSL, GetProductFinder, GetProductFinderXSL, and GetProductSearchPage are designed to retrieve very large sets of metadata that change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). When this occurs, the MessageID and CorrelationID fields aren't applicable. However, if you specify an input filter to reduce the amount of data returned, the calls retrieve the latest data (not cached). When this occurs, MessageID and CorrelationID are applicable. |
| Version | string | Conditional |
The version number of the API code that you are programming against (e.g., 549). The version you specify for a call has these basic effects: - It indicates the version of the code lists and other data that eBay should use to process your request. - It indicates the schema version you are using. You need to use a version that is greater than or equal to the lowest supported version. For the SOAP API: If you are using the SOAP API, this field is required. Specify the version of the WSDL your application is using. For the XML API: If you are using the XML API, this field has no effect. Instead, specify the version in the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header. (If you specify Version in the body of an XML API request and it is different from the value in the HTTP header, eBay returns an informational warning that the value in the HTTP header was used instead.) See: HTTP Headers (XML API Only) eBay Schema Versioning Strategy Lowest Supported Version |
| WarningLevel | WarningLevelCodeType | Optional |
Controls whether or not to return warnings when the application passes unrecognized or deprecated elements in a request. An unrecognized element is one that is not defined in any supported version of the schema. Schema element names are case-sensitive, so using WarningLevel can also help you remove any potential hidden bugs within your application due to incorrect case or spelling in field names before you put your application into the Production environment. WarningLevel only validates elements; it doesn't validate XML attributes. It also doesn't control warnings related to user-entered strings or numbers, or warnings for logical errors. We recommend that you only use this during development and debugging. Do not use this in requests in your production code. Applicable values: • High (in) Return warnings when the application passes unrecognized or deprecated elements in a request. • Low (in) Do not return warnings when the application passes unrecognized or deprecated elements in a request. This is the default value if WarningLevel is not specified. See Warning Level. |
| Call-specific Input Fields | |||
| GetRecommendationsRequestContainer | GetRecommendationsRequestContainerType (repeatable) |
Required | Specifies the data for a single item and configures the recommendation engines to use when processing the item. To retrieve recommendations for multiple items, pass a separate GetRecommendationsRequestContainer for each item. In this case, pass a user-defined correlation ID for each item to identify the matching response. |
|
GetRecommendationsRequestContainer .CorrelationID |
string | Optional | Unique key to identify the response that matches this recommendation request container. Use this key to distinguish between responses when multiple recommendation containers are specified (i.e., for batch requests). You define the key. To be useful, each correlation ID should be unique within the same call. That is, define a different correlation ID for each recommendation request container. (eBay does not validate the uniqueness of these IDs.) If specified, the same correlation ID will be returned in the corresponding recommendation response (or error response). We recommend that you use this when retrieving recommendations for multiple items at once. |
|
GetRecommendationsRequestContainer .DeletedField |
string (repeatable) |
Conditional |
Specifies the name of the field to remove from a listing. Applicable when the ListingFlow is ReviseItem or RelistItem. See ReviseItem and RelistItem for applicable values.
See: (RelistItem) DeletedField (ReviseItem) DeletedField |
|
GetRecommendationsRequestContainer .Item |
ItemType | Required |
Contains fields that describe the item for which you are seeking recommendations. If the Listing Analyzer recommendation engine is run, the applicable fields are the same as the fields for AddItem, ReviseItem, or RelistItem requests, as determined by the value specified in ListingFlow. The item ID (Item.ItemID) is required when the ListingFlow is ReviseItem or RelistItem, and it is not applicable when the ListingFlow is AddItem. All other item fields are optional, even if listed as required for other calls. However, as some tips are dependent on the properties of the item, and as some properties have dependencies on other properties, we strongly recommend that you include all the item properties that will be included in the AddItem, ReviseItem, or RelistItem request. When the Listing Analyzer engine is run, tips will only be returned for fields that are specfied on the item. When the Product Pricing engine is run, pricing data will be based on the catalog product you specify. |
|
GetRecommendationsRequestContainer .Item.ApplicationData |
string | Optional |
Returns custom, application-specific data associated with the item. The data you specify is stored by eBay with the item for your own reference, but it is not used by eBay in any way. Use ApplicationData to store special information for yourself, such as a part number. For a SKU in an eBay.com listing, use the SKU element instead. To remove this value when revising or relisting an item, use DeletedField. ApplicationData is not applicable to Half.com. For Half.com listings, use SellerInventoryID instead. Max length: 32. |
|
GetRecommendationsRequestContainer .Item.ApplyShippingDiscount |
boolean | Optional |
Multiple Item Shipping Discount. Seller specifies as input when listing, re-listing, or revising an item to indicate whether a shipping discount is to be applied when the buyer pays for the item in the checkout process and the item's transaction is combined with other transactions into an order. Returned with retrieved item data, indicating a shipping discount is applicable. Not returned by GetItem (see Item.ShippingDetails.ShippingDiscount instead). Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray |
AttributeSetArrayType | Conditional |
Item Specifics (such as new or used condition) in a listing. Item Specifics (attributes) describe category-specific aspects or features of an item in a standardized way. Carries one or more instances of AttributeSet in a list. For ID-based attributes in general, an item will be associated with no more than two full attribute sets (one for the primary category and one for the secondary category). For some international sites, an item can specify an additional site-wide attribute set for the item condition. Older applications can still use AttributeSetArray to specify a return policy (which is defined in a site-wide attribute set for most sites). However, as eBay may deprecate return policy attributes in 2009, we strongly recommend that you begin using the new Item.ReturnPolicy node instead to specify the seller's return policy. Please note that AttributeSetArray does not support the new "custom Item Specifics" model. See the ItemSpecifics node instead. For the AddItem family of calls: Some categories (such as Event Tickets and US Real Estate) require Item Specifics. See the eBay Web Services Guide links below for information on working with Item Specifics. Use GetCategory2CS and GetAttributesCS to determine when attributes are required for a category. Also use attributes to specify the item condition. For a listing to be eligible for eBay Express, the item condition is required in most cases. Use GetCategoryFeatures to determine which categories are exempt from this requirement. See the eBay Web Services Guide links below for details. For ReviseItem only: When you revise a listing, if the listing has bids and ends within 12 hours, you cannot change or add attributes. If the listing has bids but ends in more than 12 hours, you cannot change existing attribute data, but you can add attributes that were not previously specified. The most reliable way to do this is to pass in the entire AttributeSetArray with all the attributes you want in the listing (not just the ones you want to change, because that usually causes the others to be removed). To delete all attributes when you revise or relist, specify Item.AttributeSetArray in DeletedField and don't pass AttributeSetArray in the request. If the original listing's attributes are no longer valid and you get errors when you try to revise the listing, you can try to pass in the entire AttributeSetArray again with corrections. If that doesn't work, you can end the item and relist it with a set of valid attributes. For AddLiveAuctionItem and ReviseLiveAuctionItem only: For AddLiveAuctionItem and ReviseLiveAuctionItem, specify a maximum of one AttributeSet for Item Specifics that are associated with SecondaryCategory (a US eBay site category), plus any number of additional AttributeSet properties for site-wide attributes that are applicable to the US eBay site. For GetCategoryListings only: For GetCategoryListings, AttributeSetArray can return the item condition (not other Item Specifics), if specified. For GetSearchResults only: GetSearchResults can return the item condition when the request either specifies IncludeCondition as true; or specifies a product finder search (and a detail level of ItemReturnAttributes or ReturnAll). If IncludeCondition was true, see the ItemSpecific node for a simpler view of the condition value. Note: AttributeSetArray only returns the condition attribute's ValueID. You would need to use GetAttributesCS to figure out the meaning of this ID. It's easier to just look at the ItemSpecific node. If SearchRequest or TicketFinder was used to perform a product finder search, the list of attributes is limited to Item Specifics that would be included in the summary search results on the Web site, if any. At this time, GetSearchResults only returns event ticket venue name, section, and row (if specified) for eBay US (site 0); and the mileage and year for eBay Motors vehicles (site 100 and international eBay Motors sites that support this feature). In other categories, no summary attributes are returned in search results (even when the item is listed with Item Specifics.) For GetItemRecommendations only: In GetItemRecommendations, if you use the Suggested Attributes engine, the engine interprets attributes you pass in as attributes that do NOT need recommendations (i.e., attributes that the seller has already filled in as desired). The engine only returns recommendations for attributes that you do not specify, and only for attributes associated with the primary category. For Half.com, this is only returned in GetItem. It is not applicable in AddItem and other requests. See: Working with Attribute-Based Features Specifying an Item's Condition Offering a Clear Return Policy (AddItem) Item.ReturnPolicy Specify the Item Condition for Express and eBay eBay Live Auctions Revising Items that Include Item Specifics (Attributes) Relisting Items that Include Item Specifics (Attributes) |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet |
AttributeSetType (repeatable) |
Conditional |
Contains a list of attributes that describe category-specific aspects or features of an item in a standardized way. For the AddItem family of calls and GetItem, an AttributeSetArray can contain a maximum of 2 full attribute sets (one for each category in which the item is listed) if the primary and secondary categories are mapped to different characteristic sets. If they are mapped to the same characteristic set, the AttributeSetArray can contain one full attribute set. An AttributeSetArray can also contain any number of additional site-wide attribute sets. In item-listing requests, AttributeSet is required if the category is mapped to a characteristic set with required attributes. On the US site, attributes are usually required for Tickets, eBay Motors vehicles, and Real Estate listings. See GetCategory2CS and GetAttributesCS. See the Developer's Guide for information about attribute meta-data and validation rules that are applicable when listing items. In GetItem, the Half.com item condition may be returned once in an AttributeSet node with Half.com IDs and values, and once in a separate AttributeSet node with a site-wide eBay item condition. The Half.com IDs are not necessarily returned in GetAttributesCS, so you can use the eBay.com data instead. Half.com listings may also return an AttributeSet node with other eBay attributes. |
| GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet [ attribute attributeSetID ] |
int | Conditional | Constant value that identifies the attribute set in a language-independent way. Unique across all eBay sites. Corresponds to a characteristics set ID. Call GetCategory2CS to determine valid characteristics set IDs. For GetCategoryListings, you can ignore this value. Not applicable to Half.com. |
| GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet [ attribute attributeSetVersion ] |
string | Conditional |
Version of the attribute set being specified (in requests) or that is currently on the site. This value changes each time changes are made to the category-to-characteristic set mappings or characteristic set data. The current version value is not necessarily greater than the previous value. Therefore, when comparing versions, only compare whether the value has changed. In listing requests, if you do not specify this value, eBay assumes you are using the current attribute set version. If you specify the version number of the attribute meta-data that you have stored locally, eBay will compare it to the current version on the site and return a warning if the versions do not match. If an error occurs due to invalid attribute data, this warning can be useful to help you determine if you might be sending outdated data. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet.Attribute |
AttributeType (repeatable) |
Conditional |
A salient aspect or feature of an item in a given category. Attributes are known as "Item Specifics" in the eBay Web site. Use attributes to describe an item in a standard way so that buyers can find it more easily. For example, "Publication Year" is a standard attribute for books. In item-listing requests, multiple attributes can be specified. Some categories (e.g., Tickets) always require certain attributes to be specified. Therefore, in item-listing requests you need to at least specify "editable" attributes (EditType 0 and EditType 2 attributes) if they are identified as required in the attribute meta-data. See the eBay Web Services guide for information about attrribute meta-data, how to determine the valid attributes for a category, and how to determine whether attributes are required. If you are revising or relisting an item, you don't need to pass in attributes that were already specified in the original listing. To remove an optional attribute, set all its value IDs to "-100". If the item has bids (or items have been sold) but there are more than 12 hours remaining until the listing ends, you can add Attribute nodes but you cannot remove or modify data in previously specified Attribute nodes. If the item has bids and the listing ends within 12 hours, you cannot add or remove Attribute nodes or modify the contents of previously specified Attribute nodes. For GetCategoryListings, this returns the item condition only (and it is only returned if IncludeCondition = true in the request). Not applicable to Half.com. |
| GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet.Attribute [ attribute attributeID ] |
int | Conditional | Constant value that identifies the attribute in a language-independent way. Unique within the attribute set. See the Developer's Guide topics on Item Specifics and Pre-filled Item Information for information about determining valid attribute IDs. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet.Attribute.Value |
ValType (repeatable) |
Conditional |
A value the seller selected or entered for the attribute. At least one value is required for each Attribute that you specify. Some attributes can have multiple values. See the eBay Web Services guide sections on Item Specifics (Attributes) and Pre-filled Item Information (Catalogs) for information about using GetAttributesCS to determine valid attribute values. For eBay.com listings, use AttributeSetArray.AttributeSet.Attribute.Value. For Half.com, use AttributeArray.Attribute.Value. That is, the parent elements and usage for Half.com differs from eBay's standard Item Specifics format (and there is no relationship to GetAttributesCS). For Half.com, this does not use the same Attributes logic as eBay's Item Specifics. For Half.com, AttributeArray.Attribute.Value is required when you use AddItem. see the eBay Web Services Guide for valid values. You can revise AttributeArray.Attribute.Value for Half.com listings. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet.Attribute.Value .ValueID |
int | Conditional |
Constant value that identifies the attribute or characteristic in a language-independent way. Unique within the characteristic set. In item-listing requests, if the ID is defined as -3 or -6 (Other) in GetAttributesCS or GetProductSellingPages, use ValueLiteral to specify the string value that the user entered. Otherwise, use ValueID to specify the ID that is pre-defined in GetAttributesCS or GetProductSellingPages. In item-listing requests and product searches, the possible ID values are: -3 = User entered an arbitrary value (not an "Other" field) -6 = User entered a value in an "Other" field -100 = Value not specified (null) #### (integer) = Identifier for a pre-defined value that the user selected (e.g., -14 or 1001) For eBay.com, required if ValueList is specified. Not applicable to Half.com. See Attribute Elements. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet.Attribute.Value .ValueLiteral |
string | Conditional |
The descriptive name of an attribute or characteristic value (e.g., "New" might be a literal value for a Condition attribute). In item-listing requests, if you send ValueID with an id of -3 or -6, you must use ValueLiteral to enter the value the user specified. Otherwise, eBay treats the request as if no value was sent at all. For eBay.com listings, use AttributeSetArray.AttributeSet.Attribute.Value.ValueLiteral. The max length allowed varies per attribute. For GetSearchResults requests (in SearchRequest), only use ValueLiteral for attributes that support free-text values. That is, if eBay defines a value name and a unique value ID for an attribute in GetProductFinder, do not pass the name in ValueLiteral (because it won't work). Instead, specify the unique value ID in ValueID. For Half.com, use AttributeArray.Attribute.Value.ValueLiteral in listing requests. That is, the parent elements and usage for Half.com differs from eBay's standard Item Specifics format (and there is no relationship to GetAttributesCS). For Half.com, AttributeArray.Attribute.Value.ValueLiteral is required when you use AddItem. See the eBay Web Services Guide for valid values. For the Half.com Notes attribute, the max length is 500 characters. You can revise AttributeArray.Attribute.Value.ValueLiteral for Half.com listings. Max length: see description. |
|
GetRecommendationsRequestContainer .Item.AutoPay |
boolean | Conditional |
If true, the seller requests immediate payment for the item. If false or not specified, immediate payment is not requested. (In responses, does not indicate whether the item is actually still a candidate for purchase via immediate payment.) Only applicable to items listed on PayPal-enabled sites in categories that support immediate payment (see AutoPayEnabled in GetCategories), when seller has a Premier or Business PayPal account (see PayPalAccountType in Getuser). If true, the seller must also accept PayPal as a payment method for the item (see Item.PaymentMethods). Not supported if ThirdPartyCheckout is true. See the eBay Web Services guide section on Immediate Payment for additional requirements and dependencies. Also see the section on working with the eBay Motors site for additional rules. Not applicable to Half.com. Default: false. See: Requiring Immediate Payment Requiring Immediate Payment of a Vehicle Deposit |
|
GetRecommendationsRequestContainer .Item.BestOfferDetails |
BestOfferDetailsType | Optional | Container for BestOffer properties associated with the item. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.BestOfferDetails .BestOfferEnabled |
boolean | Optional | Whether best offer is enabled for this item. A seller of a fixed price format item (in a category for which Best Offer is also enabled) can opt that item into the Best Offer feature. This feature enables a buyer to make a lower priced binding offer on that item. If a listing has no active best offers, you can change this value (true to false, and vice versa). If a listing does have active best offers, you cannot change the value to false. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails |
BuyerRequirementDetailsType | Optional |
New Container for buyer requirements. The old container, BuyerRequirements, has been deprecated. All global MyeBay Buyer Requirements are over-ridden by the contents of this container. This means that buyer requirements set in MyeBay cannot be combined with buyer requirements included in this container. When this container is present in an AddItem call, all buyer requirements for the resulting listing are set by this container. Furthermore, individual buyer requirements cannot be modified or added when including this container in a ReviseItem call. The ReviseItem call needs to provide the entire set of buyer requirements to modify or add any of the requirements. Unless otherwise specified, most buyer requirements are only returned if the caller is the seller. Not applicable to Half.com.
See Selecting Buyer Requirements (eBay Web site help). |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .LinkedPayPalAccount |
boolean | Optional |
If true, only bidders with PayPal accounts linked to eBay may bid. This field can be returned even if the caller is not the seller. For AddItem, the seller's My eBay preference is automatically used with request version 453 and greater. For lower request versions, you must send in explicit BuyerRequirement input even if you have your "global" My eBay preference set to require this. Default: false. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumBuyerPolicyViolations |
MaximumBuyerPolicyViolationsType | Optional | If provided, blocks bidders who have received maximum allowed buyer policy violation reports from the sellers in the pre defined duration. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumBuyerPolicyViolations .Count |
int | Optional |
Maximum allowed buyer policy violation reports against the buyer. If the limit is reached, the buyer can not bid on this item. Used with Period. Default: 4. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumBuyerPolicyViolations .Period |
PeriodCodeType | Optional |
If a buyer fails to follow eBay policy guidelines for an auction, they may incur a buyer violation report on their account. The Period and Count elements allow a seller to specify that only buyers with a specified number of buyer violation reports within a given period of time can bid on their item. If a buyer has more buyer violation reports than specified within these limits, the buyer can not bid on this item. The Period is the past number of days (last 60 days, last 180 days, etc.) within which the buyer violation reports are calculated. Used with Count. Default: Days_30. Applicable values: • Days_30
• Days_180
• Days_360
(Not all values in PeriodCodeType apply to this field.) |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumItemRequirements |
MaximumItemRequirementsType | Optional | A means of limiting unpaying, low feedback bidders. Ignored as input if the application uses version 451 or older. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumItemRequirements .MaximumItemCount |
int | Optional | If this field is present, blocking is enabled, where the value of this field represents the maximum number of this seller's items a bidder is allowed to bid on in a 10 day period before being blocked. Valid values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 25, 50, 75, 100. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumItemRequirements .MinimumFeedbackScore |
int | Optional | This field is ignored on input unless MaximumItemCount has been provided. If this field is present, the user's feedback score is also considered: a user is blocked from bidding if the user's feedback score is less than or equal to the value of this field. Valid values: 0, 1, 2, 3, 4, 5. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumUnpaidItemStrikesInfo |
MaximumUnpaidItemStrikesInfoType | Optional | If provided, blocks bidders who have received maximum unpaid item strikes in the pre defined duration by the seller. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumUnpaidItemStrikesInfo .Count |
int | Optional |
Maximum allowed unpaid item strikes against the buyer. If the limit is reached, the buyer can not bid on this item. Used with Period. Default: 2. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumUnpaidItemStrikesInfo .Period |
PeriodCodeType | Optional |
If a buyer fails to pay for an item, they incur an unpaid item strike on their account. The Period and Count elements allow a seller to specify that only buyers with a specified number of item strikes (or less) within a given period of time can bid on their item. If a buyer has more strikes than specified within these limits, the buyer can not bid on this item. The Period is the past number of days (last 60 days, last 180 days, etc.) within which the unpaid item buyer strikes are calculated. Used with Count. Default: Days_30. Applicable values: • Days_30
• Days_180
• Days_360
(Not all values in PeriodCodeType apply to this field.) |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MinimumFeedbackScore |
int | Optional | If true, blocks bidders with this feedback score or lower. Ignored as input if the application uses version 451 or older. Valid values: -3, -2, -1. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .ShipToRegistrationCountry |
boolean | Optional |
If true, blocks bidders who are registered in countries to which the seller has specified he will not shipo. Ignored as input if the application uses version 451 or older. Default: false. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .VerifiedUserRequirements |
VerifiedUserRequirementsType | Optional | A means of limiting unverified bidders. Ignored as input if the application uses version 451 or older. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .VerifiedUserRequirements .MinimumFeedbackScore |
int | Optional |
This field is ignored unless VerifiedUser is true. If this field is present, the user's feedback score is also considered: a user is blocked from bidding if the user's feedback score is less than or equal to the value of this field. Default: 5. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .VerifiedUserRequirements .VerifiedUser |
boolean | Optional |
If true, blocks bidding by users who do not pass a simple check (for example, for credit card on file). See "Buyer Requirements - VerifiedUser" in the chapter "Field Differences for eBay Sites." Default: false. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .ZeroFeedbackScore |
boolean | Optional |
If true, blocks bidders with a feedback score of 0 who attempt to bid on Buy It Now items worth 100 RMB or more. Ignored as input if the application uses version 451 or older. This requirement is only enabled for the CN site. Default: false. |
|
GetRecommendationsRequestContainer .Item .BuyerResponsibleForShipping |
boolean | Optional |
Applicable for listings in vehicle categories on the US eBay Motors site and eBay Canada site. (No business effect if specified for other categories or sites, as the Web site will not display the information to buyers.) If true, the buyer is responsible for vehicle pickup or shipping. If false, specify vehicle shipping arrangements in the item description. Default is true. (The description can also include vehicle shipping arrangements when this value is true.) If the item has bids or ends within 12 hours, you cannot modify this flag. Do not specify ShippingDetails.ShippingServiceOptions for vehicle listings. If true and the listing is on the US eBay Motors site, and you want the listing to be visible on the eBay Canada site, set Item.ShipToLocations to CA. If true and the listing is on the eBay Canada site , and you want your listing to be visible on the US eBay Motors site, set Item.ShipToLocations to US. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.BuyItNowPrice |
AmountType (double) | Optional |
For Chinese auction listings, Buy It Now allows a user to purchase the item at a fixed price and end the auction immediately. Use this field to add Buy It Now and specify the amount a buyer would need to bid to take advantage of the Buy It Now feature. On the main eBay site, not applicable to fixed-price items (ListingType values StoresFixedPrice or FixedPriceItem), AdFormat listings, or Half.com listings. For fixed-price and Half.com listings, see StartPrice instead. See the eBay Web Services Guide for validation rules when revising US eBay Motors listings, including rules for lowering the Buy It Now price of a Motors listing. Once a Chinese auction has bids (and the high bid exceeds the reserve price, if any), the listing is no longer eligible for Buy It Now (with some exceptions noted below). However, calls like GetItem and GetSearchResults still return the BuyItNowPrice that the seller originally set for the listing. You can use Item.SellingStatus.BidCount to determine whether an auction with Buy It Now has bids or not. With GetSearchResults, you can use the Item.SearchDetails.BuyItNowEnabled flag to determine whether the item can still be purchased using Buy It Now. With GetItem, you can use the Item.ListingDetails.BuyItNowAvailable flag to determine whether the item can still be purchased using Buy It Now. On some sites, the Buy It Now price for a Chinese auction may remain available for certain categories even after a bid is placed. See the "Longer Lasting Buy It Now" link below for more details and the latest list of eBay US categories that support this behavior. The eBay Spain site supports this behavior for all categories. For a listing to be eligible for Express, the max Buy It Now Price is USD 10,000.00 for the US. (Additional price limits may be imposed by the seller's PayPal account or the payment method used. Such limits cannot be determined via the eBay API and are not covered in eBay's API documentation, as they may vary for each user.) To remove this value when revising or relisting an item, use DeletedField. See: Longer Lasting Buy It Now Specify a Fixed Price for Express and eBay Revising US eBay Motors Listings |
|
GetRecommendationsRequestContainer .Item .CategoryBasedAttributesPrefill |
boolean | Optional |
Allows eBay to auto-fill some of a listing's Item Specifics (attribute) values based on the listing's category (or categories). Auto-filling attributes based on a category is not the same as using Pre-filled Item Information based on a catalog product (see ProductListingDetails). If true, also specify Item.CategoryMappingAllowed with a value of true. (Alternatively, you can auto-fill attributes on the client side by using mapping meta-data returned by GetAttributesCS.) See the eBay Web Services guide for more information. Ignored if the category does not support auto-filling attributes. If you also pass in attributes in AttributeSetArray, your values will override any auto-filled values for the same attributes. Once you have overridden the value of an auto-filled attribute for a given listing, eBay will not auto-fill it on subsequent ReviseItem requests (even if you remove the overridden value). Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.CategoryMappingAllowed |
boolean | Optional |
Controls how eBay handles cases in which an ID specified in PrimaryCategory and/or SecondaryCategory no longer exists in the current category structure: If you pass a value of true in CategoryMappingAllowed, eBay will look up the current ID that is mapped to the same category and use the new ID for the listing (if any). The new ID will be returned in the response as CategoryID (for the primary category) or Category2ID (for the secondary category). If CategoryMappingAllowed is not set or contains a value of "false" (the default), an error will be returned if a selected category ID no longer exists. Not applicable to Half.com.
See Mapping Old Category IDs to Current IDs. |
|
GetRecommendationsRequestContainer .Item.Charity |
CharityType | Optional |
Identifies a Giving Works listing and the benefiting nonprofit charity organization selected by the charity seller, if any. If specified, the seller must also accept PayPal as a payment method for the item (see Item.PaymentMethods). Giving Works listings are not eligible for some eBay Express sites. (If ExpressListing is false in GetItem or VerifyAddItem and you specified Charity, check whether ExpressItemRequirements returns NoCharity as a cause.) When you revise an item, you can add a charity to a non-charity listing, but you cannot remove or change the charity designation. The rules for adding a charity to a listing depend on the listing type. For an auction listing, you can revise an item to add a charity if there are more than 12 hours left for the listing (whether or not the item has bids). For a fixed-price listing, you can revise an item to add a charity if there are more than 12 hours left for the listing, and the item has not been sold. For a Store Inventory listing, you can revise an item to add a charity if the item has not been sold. You cannot revise listings to add charity for Ad Format listings. When you relist an item, use DeletedField to remove charity information. Not applicable to Half.com. See: Miscellaneous Item Field Differences Identifying Listings that Benefit Nonprofits |
|
GetRecommendationsRequestContainer .Item.Charity.CharityID |
string | Conditional | A unique identification number assigned by eBay to registered nonprofit charity organizations. Required input when listing Giving Works items. |
|
GetRecommendationsRequestContainer .Item.Charity.CharityNumber |
int | Optional | A unique identification number assigned to a nonprofit charity organization by the dedicated provider of eBay Giving Works. Being superseded by CharityID. Max 10 digits. |
|
GetRecommendationsRequestContainer .Item.Charity.Donation | |||