This call examines 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 Testing GetItemRecommendations in the Trading API Guide.
If ConditionID is supported for a category (per GetCategoryFeatures), item condition recommendations are suppressed with request version 661 and higher in the sandbox and with request version 667 and higher in production.
See:
Introduction to Pictures in Item Listings
GetItemRecommendations
Getting Recommendations to Improve a Listing
Working with Custom Item Specifics
See also the reference documentation for these calls:
| 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 does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).
<?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 ... -->
<ExcludeRelationships> boolean </ExcludeRelationships>
<IncludeConfidence> boolean </IncludeConfidence>
<Item> ItemType
<ApplicationData> string </ApplicationData>
<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
<NameValueList> NameValueListType
<Name> string </Name>
<Value> string </Value>
<!-- ... more Value nodes here ... -->
</NameValueList>
<!-- ... more NameValueList nodes here ... -->
</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>
<PaymentDetails> PaymentDetailsType
<DaysToFullPayment> int </DaysToFullPayment>
<DepositAmount> AmountType (double) </DepositAmount>
<DepositType> DepositTypeCodeType </DepositType>
<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>
<ProductReferenceID> string </ProductReferenceID>
<TicketListingDetails> TicketListingDetailsType
<PrintedTime> string </PrintedTime>
</TicketListingDetails>
<UseStockPhotoURLAsGallery> boolean </UseStockPhotoURLAsGallery>
</ProductListingDetails>
<Quantity> int </Quantity>
<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>
<SellerProvidedTitle> string </SellerProvidedTitle>
<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>
<ExcludeShipToLocation> string </ExcludeShipToLocation>
<!-- ... more ExcludeShipToLocation nodes here ... -->
<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>
<VIN> string </VIN>
<VRM> string </VRM>
</Item>
<ListingFlow> ListingFlowCodeType </ListingFlow>
<Query> string </Query>
<RecommendationEngine> RecommendationEngineCodeType </RecommendationEngine>
<!-- ... more RecommendationEngine nodes here ... -->
</GetRecommendationsRequestContainer>
<!-- ... more GetRecommendationsRequestContainer nodes here ... -->
</GetItemRecommendationsRequest>
| Argument | Type | Occurrence | 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 |
| 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:
|
| 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 | Required,
repeatable: [1..*] |
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 | Conditional,
repeatable: [0..*] |
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. |
|
GetRecommendationsRequestContainer .ExcludeRelationships |
boolean | Optional |
If true, the Relationship node is not returned for any recommendations. Relationship recommendations tell you whether an Item Specific value has a logical dependency on another Item Specific. For example, in a clothing category, Size Type could be recommended as a parent of Size, because Size=Small would mean something different to buyers depending on whether Size Type=Petite or Size Type=Plus. In general, it is a good idea to retrieve and use relationship recommendations, as this data can help buyers find the items they want more easily. Only applicable when RecommendationEngine=ItemSpecifics. Default: false. |
|
GetRecommendationsRequestContainer .IncludeConfidence |
boolean | Optional |
If true, returns eBay's level of confidence for each name and value. Some sellers may find this useful when choosing whether to use eBay's recommendation or their own name or value. Only applicable when RecommendationEngine=ItemSpecifics. Default: false. |
|
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. Not applicable to Half.com, use SellerInventoryID instead. Max length: 32. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray |
AttributeSetArrayType | Conditional |
Deprecated as of version 773. Currently ignored. Use Item.ItemSpecifics instead. An older format for describing item specifics. Most eBay categories no longer support ID-based attributes. The remaining categories (e.g., US eBay Motors) will drop support for ID-based attributes by May 2012. New applications should not use ID-based attributes. Existing applications should be updated to remove all dependencies on ID-based attributes now. Instead, use ItemSpecifics for the newer Custom Item Specifics model. AttributeSetArray contains a maximum of two AttributeSet fields in a list (one for the primary category and one for the secondary category). Use GetCategory2CS and GetAttributesCS to determine which attributes are required for a given category. But first check GetCategoryFeatures to determine whether the newer ItemSpecifics format is supported instead. 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 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 for Half.com items. See:
Deprecation version: 773. See also Deprecated Objects. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet |
AttributeSetType | Conditional,
repeatable: [0..*] |
Deprecated as of version 773. 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. Deprecation version: 773. See also Deprecated Objects. |
| GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet [ attribute attributeSetID ] |
int | Conditional | Deprecated as of version 773. 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. Not applicable to Half.com. |
| GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet [ attribute attributeSetVersion ] |
string | Conditional |
Deprecated as of version 773.
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 | Conditional,
repeatable: [0..*] |
Deprecated as of version 773. 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 attribute 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. Not applicable to Half.com. Deprecation version: 773. See also Deprecated Objects. |
| GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet.Attribute [ attribute attributeID ] |
int | Conditional | Deprecated as of version 773. 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 | Conditional,
repeatable: [0..*] |
Deprecated as of version 773. 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. Deprecation version: 773. See also Deprecated Objects. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet.Attribute.Value .ValueID |
int | Conditional |
Deprecated as of version 773. 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. Deprecation version: 773. See also Deprecated Objects. |
|
GetRecommendationsRequestContainer .Item.AttributeSetArray .AttributeSet.Attribute.Value .ValueLiteral |
string | Conditional |
Deprecated as of version 773. 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 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. Deprecation version: 773. See also Deprecated Objects. |
|
GetRecommendationsRequestContainer .Item.AutoPay |
boolean | Conditional |
To create an immediate payment listing, AutoPay must be included and set to True for the Add/Revise/Relist API calls. If the seller does not want to create an immediate payment item, this field is either omitted, or included and set to False. In the API calls that return the AutoPay field, be aware that the field's appearance in the output does not necessarily indicate that the listing contains an immediate payment item, but only that the seller attempted to create (by including and setting AutoPay to True in the request) an immediate payment. Some requirements (discussed below) must be met in order for a seller to list an immediate payment item. Only sellers with Premier or Business PayPal accounts can specify immediate payment for an item. Also, the item must be listed on a site that supports PayPal payments, and listed in a category that supports immediate payment. To discover if a category supports immediate payment for an item, use GetCategories and look for the appearance of AutoPayEnabled in the output. AutoPayEnabled is returned as an empty element if the category supports immediate payment, and is not returned at all if the category does not support immediate payment. In addition to the preceding requirements, the seller must have specified PayPal as a payment method for the listing. To create, revise, or relist an immediate payment listing, AutoPay must be included and set to True, the PayPalEmailAddress value must be a valid PayPal email address for the seller, and PayPal must be included as a payment method. Not applicable to Half.com. Default: false. See:
|
|
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 |
When this container is present in an AddItem or AddFixedPriceItem 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. All global My eBay Buyer Requirements are overridden by the contents of this container. This means that buyer requirements set in My eBay cannot be combined with buyer requirements included in this container. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .LinkedPayPalAccount |
boolean | Optional |
If true, only bidders with PayPal accounts 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 preferences set to require PayPal. Default: false. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumBuyerPolicyViolations |
MaximumBuyerPolicyViolationsType | Optional | If provided, blocks bidders who have received the maximum allowed buyer policy violation reports (in a specific time period) from bidding on this item. |
|
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
(Not all values in PeriodCodeType apply to this field.) |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumItemRequirements |
MaximumItemRequirementsType | Optional | If this field is included in your call, you can limit unpaying or low feedback bidders, by setting the MaximumItemCount and MinimumFeedbackScore to define when a bidder is blocked from bidding. Ignored as input if the application uses version 451 or older. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .MaximumItemRequirements .MaximumItemCount |
int | Optional | If this field is present, user blocking is enabled for both bidding and buying. The value of this field specifies the maximum number of this seller's items a bidder is allowed to bid on or buy 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 MaximumItemCount is included in the call, both MaximumItemCount and MinimumFeedbackScore are used to determine whether the bidder is blocked from bidding. A user is blocked from bidding if they have reached or exceeded the MaximumItemCount and 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 the maximum unpaid item strikes (in a specific time period) from bidding on this item. |
|
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 where the seller has specified that he will not ship. Ignored as input if the application uses version 451 or older. Default: false. |
|
GetRecommendationsRequestContainer .Item.BuyerRequirementDetails .VerifiedUserRequirements |
VerifiedUserRequirementsType | Optional |
If provided, blocks bidders who do not pass a simple check (for example, for credit card on file). Applies to the following eBay sites only:
|
|
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 |
Note: In late October 2010, for the US site, users who are registering as eBay sellers for the first time are subject to seller limits which limit the quantity of items and/or the total listing value of the items. This applies to new sellers, not currently to existing sellers. (The GetMyeBaySelling call returns the remaining item quantity and remaining total value under the limits for the seller, if any such limits exist for the seller.) If a call to add an item or revise an item would result in the exceeding of these limits, the add item or revise item call will fail. For auctions, the value limits apply to the start price, not the final sale amount. For more information, see the link to Seller Limits below. For 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. This feature is not applicable to fixed price listings, AdFormat listings, or Half.com listings. See the Trading API Guide for validation rules when revising US eBay Motors listings, including rules for lowering the Buy It Now price of a Motors listing. Once an auction has bids (and the high bid exceeds the reserve price, if specified), the listing is no longer eligible for Buy It Now (with some exceptions noted below). However, calls like GetItem 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 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 an 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. There might be price limits imposed for Buy It Now items, subject to 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 because they can vary for each user. To remove this value when revising or relisting an item, use DeletedField. See:
|
|
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 Trading API 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. |
|
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). 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:
|
|
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.DonationPercent |
float | Conditional | The percentage of the purchase price that the seller chooses to donate to the selected nonprofit organization. This percentage is displayed in the Giving Works item listing. Possible values: 10.0 to 100.0. Percentages must increment by 5.0. Minimum donation percentages may be required for Giving Works listings, see http://pages.ebay.com/help/sell/selling-nonprofit.html for details. DonationPercent is required input when listing Giving Works items. |
|
GetRecommendationsRequestContainer .Item.Currency |
CurrencyCodeType | Required |
Currency associated with the item's price information. 3-letter ISO 4217 currency code that corresponds to the site specified in the item-listing request. Also applicable as input to AddItem and related calls when you list items to Half.com (specify USD). You cannot modify a listing's currency when you revise or relist an item.
Applicable values: • AUD (in/out) Australian Dollar. For eBay, you can only specify this currency for listings you submit to the Australia site (site ID 15). • CAD (in/out) Canadian Dollar. For eBay, you can only specify this currency for listings you submit to the Canada site (site ID 2) (Items listed on the Canada site can also specify USD.) • CHF (in/out) Swiss Franc. For eBay, you can only specify this currency for listings you submit to the Switzerland site (site ID 193). • CNY
• EUR (in/out) Euro. For eBay, you can only specify this currency for listings you submit to these sites: Austria (site 16), Belgium_French (site 23), France (site 71), Germany (site 77), Italy (site 101), Belgium_Dutch (site 123), Netherlands (site 146), Spain (site 186), Ireland (site 205). • GBP (in/out) Pound Sterling. For eBay, you can only specify this currency for listings you submit to the UK site (site ID 3). • HKD (in/out) Hong Kong Dollar. For eBay, you can only specify this currency for listings you submit to the Hong Kong site (site ID 201). • INR (in/out) Indian Rupee. For eBay, you can only specify this currency for listings you submit to the India site (site ID 203). • MYR (in/out) Malaysian Ringgit. For eBay, you can only specify this currency for listings you submit to the Malaysia site (site ID 207). • PHP (in/out) Philippines Peso. For eBay, you can only specify this currency for listings you submit to the Philippines site (site ID 211). • PLN (in/out) Poland, Zloty. For eBay, you can only specify this currency for listings you submit to the Poland site (site ID 212). • SEK (in/out) Swedish Krona. For eBay, you can only specify this currency for listings you submit to the Sweden site (site 218). • SGD (in/out) Singapore Dollar. For eBay, you can only specify this currency for listings you submit to the Singapore site (site 216). • TWD (in/out) New Taiwan Dollar. This value is not applicable since the API is not used with new eBay Taiwan site. • USD (in/out) US Dollar. For eBay, you can only specify this currency for listings you submit to the US (site ID 0), eBayMotors (site 100), and Canada (site 2) sites. (Not all values in CurrencyCodeType apply to this field.) |
|
GetRecommendationsRequestContainer .Item.Description |
string | Conditional |
The seller's description of the item. In listing requests, you can submit your description using CDATA if you want to use HTML or XML-reserved characters in the description. An error is returned if this contains malicious JavaScript content. (For related eBay policy, see http://pages.ebay.com/help/policies/listing-javascript.html.) If you embed pictures in the description (by using IMG tags) instead of using PictureURL, but you want a camera icon to appear in search and listing pages, specify the following null-image URL in PictureURL: http://pics.ebay.com/aw/pics/dot_clear.gif. See "Including Pictures in an Item Listing" in the Trading API Guide. Required for all listings, except listings that include eBay catalog product details. Optional when you list with product details and Item.ProductListingDetails.IncludePrefilledItemInformation is true. For GetItem: Item.Description can be empty when IncludePrefilledItemInformation is true and the seller did not write their own description. Item.Description doesn't return pre-filled descriptions from catalogs. The eBay site shows the catalog product description (if any) in the product details section of a listing. To retrieve a URL for the catalog product details page, see DetailsURL in GetProductSearchResults, GetProductFamilyMembers, or GetProductSellingPages. Or see DetailsURL in FindProducts in the Shopping API (which may be easier to use if your application doesn't support eBay Attributes). Not applicable to Half.com. (For Half.com, use AttributeArray.Attribute with attributeLabel="Notes" to specify a brief description or note to the buyer.) Max length: 500000 (some sites may allow more, but the exact number may vary). |
|
GetRecommendationsRequestContainer .Item.DisableBuyerRequirements |
boolean | Optional |
If true: all buyer requirements (from Item.BuyerRequirementDetails or Buyer requirements preferences in My eBay) are ignored. If false (or omitted): Item.BuyerRequirementDetails or Buyer requirements preferences are used, with Item.BuyerRequirementDetails having the higher precedence. Default: false. |
|
GetRecommendationsRequestContainer .Item.DispatchTimeMax |
int | Conditional |
Specifies the maximum number of business days the seller commits to for preparing an item to be shipped after receiving a cleared payment. This time does not include the shipping time (the carrier's transit time). For the AddItem family of calls: Required for listings in certain categories when certain shipping services (with delivery) are offered. See HandlingTimeEnabled in GetCategoryFeatures. The seller sets this to a positive integer value corresponding to the number of days. For a list of allowed values on each eBay site, use DispatchTimeMaxDetails in GeteBayDetails. (Typical values are 1, 2, 3, 4, 5, 10, 15, or 20, but this can vary by site and these may change over time.) Valid for flat and calculated shipping. Does not apply when there is no shipping, when it is local pickup only or it is freight shipping. For example, when ShippingService=Pickup or ShipToLocations=None, then DispatchTimeMax is not required (or it can be 0). To add Get It Fast to listings (for domestic shipping), in addition to setting GetItFast to true, DispatchTimeMax must be set to 1 and the seller must specify at least one qualifying expedited shipping service. For ReviseItem only: If the listing has bids or sales and it ends within 12 hours, you can't change this value. If the listing is a GTC listing that has sales or ends within 12 hours (one or the other, but not both), you can add or change this value. If the listing has no bids or sales and more than 12 hours remain before the listing ends, you can add or change the dispatch (handling) time. For GetItem: GetItem returns DispatchTimeMax only when shipping service options are specified for the item and the seller specified a dispatch time. See:
|
|
GetRecommendationsRequestContainer .Item.ExternalProductID |
ExternalProductIDType | Conditional |
This field will be deprecated in a future project. New applications should use ProductListingDetails instead of ExternalProductID for AddItem and related calls. Contains an ISBN value, UPC value, EAN value, ticket keywords, or eBay catalog product ID. Causes eBay to list the item with Pre-filled Item Information based on the value you specify. Only applicable to certain categories. See the eBay Trading API Guide for information on the categories that currently support usage of this field. For AddItem and VerifyAddItem only: On the US site, if you are listing in a media category, eBay determines the primary category ID based on the product ID you specify (and CategoryID is usually ignored). To avoid confusion (e.g., at revise/relist time), it's a good idea to avoid specifying the primary category in combination with ExternalProductID. Note: There may be cases when the category ID can't be determined and you get an error. If this does occur, then specify the category ID. If you are listing in two categories and both are catalog-enabled, the external ID should be for a product associated with the primary category. If only one category is catalog-enabled, the external ID should be for a product that is associated with the catalog-enabled category. If you are listing an event ticket, the primary category is required, and the external ID must be associated with the primary category. Either Item.ExternalProductID or Item.ProductListingDetails can be specified in an AddItem (or VerifyAddItem) request. Do not specify both. If you use Item.ExternalProductID instead of Item.ProductListingDetails, eBay sets IncludeStockPhotoURL and IncludePrefilledItemInformation to true automatically. Optional for eBay.com listings. Applicable to Half.com listings. For ReviseItem and RelistItem only: ExternalProductID is not applicable when revising and relisting items (use Item.ProductListingDetails instead). For GetItemRecommendations only: In GetItemRecommendations, only applicable when the value of ListingFlow is AddItem. Not applicable when the recommendation engine is ProductPricing. See:
|
|
GetRecommendationsRequestContainer .Item.ExternalProductID .ReturnSearchResultOnDuplicates |
boolean | Optional | Applicable for listing use cases only (not buy-side searching). Indicates what eBay should do if more than one product matches the value passed in Value. Only takes effect when more than one match is found. If true, the response should include an error and all matching product IDs. If false, the response should include an error but should not return the matching product IDs. This field is also applicable when listing Half.com items. |
|
GetRecommendationsRequestContainer .Item.ExternalProductID.Type |
ExternalProductCodeType | Conditional |
The kind of identifier being used. The choices are listed For requests, required if Value is specified. For Half.com listing use cases, only ISBN, UPC, and EAN are supported. GetProducts supports ISBN, UPC, and EAN. Applicable values: • CustomCode (in) Reserved for internal or future use • EAN (in/out) ExternalProductID.Value contains an EAN value. Required when you pass an EAN as the external product ID. • ISBN (in/out) ExternalProductID.Value contains an ISBN value. Required when you pass an ISBN as the external product ID. (This value is also applicable to Half.com listings.) • Keywords (in) ExternalProductID.Value contains a set of keywords that uniquely identify the product. Only applicable when listing event ticket. See the eBay Web Services guide for information about valid ticket keywords for an external product ID. Required when you pass a set of keywords as the external product ID. Not applicable with GetProducts. • ProductID (in) ExternalProductID.Value contains an eBay catalog product ID. Required when you pass an eBay product ID as the external product ID. Not applicable with GetProducts. • UPC (in/out) ExternalProductID.Value contains a UPC value. Required when you pass a UPC as the external product ID. (This value is also applicable to Half.com listings.) (Not all values in ExternalProductCodeType apply to this field.) |
|
GetRecommendationsRequestContainer .Item.ExternalProductID.Value |
string | Conditional |
An industry-standard value that uniquely identifies the product. The valid values are dictated by the Type property. Required if Type is specified. Max length 13 for ISBN (as of February 2007), 13 for EAN, 12 for UPC, and 4000 for ProductID. No max length for ticket keywords (but passing too much data can result in "no match found" errors). For AddItem and related calls: If the primary and secondary categories are both catalog-enabled, the value must apply to the primary category. Event tickets listings support a set of keywords that uniquely identify the listing. The ticket keywords specify the event name (the title shown on the ticket), venue name, and event date and time. See the eBay Web Services guide for more information and validation rules. For convenience, you can pass an eBay product ID as input (not limited to media categories). Required for Half.com listing use cases, and this can only be an ISBN, UPC, or EAN value. For GetProducts input only: Only ISBN, EAN, and UPC values are currently supported as input. For GetProducts and GetSellerPayments output only: Also see AlternateValue, which is returned if the catalog defines multiple ISBN values (e.g., one for ISBN-13 and one for ISBN-10). Please note that some catalogs return ISBN values that are not 10 or 13 characters, and some values contain non-alphanumeric symbols (e.g., $). Max length: See description. |
|
GetRecommendationsRequestContainer .Item.GetItFast |
boolean | Optional |
Indicates whether the seller has committed to the GetItFast shipping rules for this listing. If the GetItFast field is set to true, and the seller's first priority domestic shipping service (the service that has the ShippingServicePriority field set to 1) is an expedited shipping service, then every shipping service offered for this listing is considered a GetItFast service. Therefore, the seller commits to delivering the item to the buyer-selected shipping service within one day. Not supported for UK Store Inventory format items. Not applicable to Half.com. See:
|
|
GetRecommendationsRequestContainer .Item.GiftIcon |
int | Conditional |
If true, a generic gift icon displays next the listing's title in search and browse pages. GiftIcon must be set to be able to use GiftServices options. Note that one/zero is returned instead of true/false. When the Top-Rated Seller program became operational, some enhanced listing features were removed or restricted to certain sellers on some sites. Use GeteBayDetails ListingFeatureDetails for more information. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.GiftServices |
GiftServicesCodeType | Optional,
repeatable: [0..*] |
Optional gift services that the seller is offering if the buyer chooses to purchase the item as a gift. Only returned if offered by the seller. When the Top-Rated Seller program became operational, some enhanced listing features were removed or restricted to certain sellers on some sites. Use GeteBayDetails ListingFeatureDetails for more information. Not applicable to Half.com. Applicable values: • CustomCode (in/out) Reserved for internal or future use • GiftExpressShipping (in/out) The seller is offering to ship the item via an express shipping method as explained in the item description. • GiftShipToRecipient (in/out) The seller is offering to ship to the gift recipient (instead of to the buyer) after payment clears. • GiftWrap (in/out) The seller is offering to wrap the item (and optionally include a card) as explained in the item description. |
|
GetRecommendationsRequestContainer .Item.HitCounter |
HitCounterCodeType | Optional |
Indicates whether an optional hit counter is displayed on the item's listing page and, if so, what type. See HitCounterCodeType for specific values. Not applicable to Half.com. Applicable values: • BasicStyle (in/out) A basic style hit counter. • CustomCode (in/out) Reserved for internal or future use • GreenLED (in/out) A green LED, computer-style hit counter (US only). Non-US sites will return errors if they use GreenLED as input, and should use RetroStyle instead. • Hidden (in/out) A hidden hit counter (US only). The number of page views will only be available to the item's seller. For faster "View Item" page loads, use HiddenStyle. • HiddenStyle (in/out) A hidden hit counter. The number of page views will only be available to the item's seller. • HonestyStyle (in/out) A basic style hit counter (US only). Non-US sites will return errors if they use HonestyStyle as input, and should use BasicStyle instead. • NoHitCounter (in/out) No hit counter. The number of page views will not be available. • RetroStyle (in/out) A retro, computer-style hit counter. |
|
GetRecommendationsRequestContainer .Item.ItemID |
ItemIDType (string) | Conditional |
The ID that uniquely identifies the item listing. The ID is generated by eBay after an item is listed. You cannot choose or revise this value. Also applicable to Half.com. For Half.com, you can specify either ItemID or SellerInventoryID in a ReviseItem request to uniquely identify the listing. In order retrieval calls (such as, GetOrders), use the OrderLineItemID (which is a concatenation of ItemID and TransactionID to uniquely identify an order line item. With multi-quantity listings, a single ItemID can be associated with more than one TransactionID. (For single-quantity listings, the TransactionID is 0.) In GetItemRecommendations, the item ID is required when the value of ListingFlow is ReviseItem or RelistItem, but it is not applicable when the value of ListingFlow is AddItem. Note: Although we represent item IDs as strings in the schema, we recommend you store them as 64-bit signed integers. If you choose to store item IDs as strings, allocate at least 19 characters (assuming decimal digits are used) to hold them. eBay will increase the size of IDs over time. Your code should be prepared to handle IDs of up to 19 digits. For more information about item IDs, see Common FAQs on eBay Item IDs and other eBay IDs in the Knowledge Base. Max length: 19 (Note: the eBay database specifies 38. Currently, Item IDs are usually 9 to 12 digits). |
|
GetRecommendationsRequestContainer .Item.ItemSpecifics |
NameValueListArrayType | Optional |
A list of Item Specific name and value pairs that the seller specified for the item. Item Specifics describe well-known aspects of an item or product in a standard way, to help buyers find that type of item or product more easily. or example, "Publication Year" is a typical aspect of books, and "Megapixels" is a typical aspect of digital cameras. In the AddItem family of calls, use Item.ItemSpecifics to specify custom Item Specifics. To determine which categories support custom Item Specifics, use GetCategoryFeatures. To retrieve recommended Item Specifics, use GetCategorySpecifics or GetItemRecommendations. In GetItemRecommendations, pass in the PrimaryCategory and (optionally) Title to retrieve recommended names and values. With GetItem, this is only returned when you specify IncludeItemSpecifics in the request (and the seller included custom Item Specifics in their listing). For ReviseItem only: When you revise a listing, if the listing has bids and ends within 12 hours, you cannot change or add Item Specifics. If the listing has bids but ends in more than 12 hours, you cannot change existing Item Specifics, but you can add Item Specifics that were not previously specified. To delete all Item Specifics when you revise or relist, specify Item.ItemSpecifics in DeletedField and don't pass ItemSpecifics in the request. With GetProducts, only the item condition is returned at the item level. Additional attributes that were pre-filled from the catalog are returned in Product.ItemSpecifics. Note: To specify an item's condition, use the ConditionID field instead of a condition item specific. Use GetCategoryFeatures to see which categories support ConditionID and to get a list of valid condition IDs. (If you specify ConditionID and you also specify Condition as a custom item specific, eBay drops the condition item specific.) See:
|
|
GetRecommendationsRequestContainer .Item.ItemSpecifics .NameValueList |
NameValueListType | Conditional,
repeatable: [0..*] |
For the AddItem family of calls: Contains the name and value(s) for an Item Specific. Only required when the ItemSpecifics container is specified. For the AddFixedPriceItem family of calls: The same NameValueList schema is used for the ItemSpecifics node, the VariationSpecifics node, and the VariationSpecifcsSet node. If the listing has varations, any name that you use in the VariationSpecifics and VariationSpecificsSet nodes can't be used in the ItemSpecifics node. When you list with Item Variations: a) Specify shared Item Specifics (e.g., Brand) in the ItemSpecifics node. b) Specify up to five VariationSpecifics in each Variation node. c) Specify all applicable names with all their supported values in the VariationSpecificSet node. See the Variation sample in the AddFixedPriceItem call reference for examples. For PlaceOffer: Required if the item being purchased includes Item Variations. |
|
GetRecommendationsRequestContainer .Item.ItemSpecifics .NameValueList.Name |
string | Conditional |
A name in a name/value pair. For the AddItem and AddFixedPriceItem families of calls: In the Item.ItemSpecifics context, this can be any name that the seller wants to use. However, to help buyers find items more easily, it is a good idea to try to use a recommended name when possible (see GetCategorySpecifics or GetItemRecommendations). You can't specify the same name twice within the same listing. For the AddFixedPriceItem family of calls: In the VariationSpecifics context, this can be any name that the seller wants to use, unless the VariationsEnabled flag is false for the name in the GetCategorySpecifics response. For example, for some categories eBay may recommend that you only use "Brand" as a shared name at the Item level, not in variations. For GetCategorySpecifics and GetItemRecommendations: This is a recommended (popular) name to use for items in the specified category (e.g., "Brand" might be recommended, not "Manufacturer"). In the GetProducts response, this is an attribute name that is defined for a catalog product. For PlaceOffer: Required if the item being purchased includes Item Variations. |
|
GetRecommendationsRequestContainer .Item.ItemSpecifics .NameValueList.Value |
string | Conditional,
repeatable: [0..*] |
A value associated with the name. For the AddItem family of calls: If you specify multiple values for Item Specifics, eBay only stores the first one, unless GetCategorySpecifics or GetItemRecommendations indicates that the corresponding name supports multiple values. For the AddFixedPriceItem family of calls: If you specify multiple values for Item Specifics or Variation Specifics, eBay only stores the first one, unless GetCategorySpecifics or GetItemRecommendations indicates that the corresponding name supports multiple values. In VariationSpecificSet, you typically specify multiple Value fields for each name. For example, if Name=Size, you would specify all size values that you wan to offer in the listing. For GetCategorySpecifics and GetItemRecommendations: The most highly recommended values are returned first. For these calls, Value is only returned when recommended values are available. For PlaceOffer: Required if the item being purchased includes Item Variations. Max length: 50 (see GeteBayDetails). |
|
GetRecommendationsRequestContainer .Item.LimitedWarrantyEligible |
boolean | Conditional |
Deprecated as of version 675. Currently ignored. This feature is no longer supported. This field will be removed from the schema in an upcoming release. Applicable to US eBay Motors vehicle listings only. If false, the vehicle was not considered for a limited warranty by eBay. If your application lists Motors vehicles, you were required to provide the seller with an opportunity to indicate whether the vehicle has not been modified and is not a special type (e.g., Corvette ZR1). If LimitedWarrantyEligible was passed in, it meant the application presented the seller with checkboxes to indicate this information. If true, the seller verified that the vehicle has not been modified and is not a special type. If false, the seller verified that vehicle has been modified or it is a special type. Passing a value of true did not guarantee that eBay would offer a limited warranty. It only made the listing eligible for consideration. Not applicable to Half.com. See Short-Term Service Agreement (Limited Warranty). Deprecation version: 675. See also Deprecated Objects. |
|
GetRecommendationsRequestContainer .Item.ListingDesigner |
ListingDesignerType | Optional |
Contains the detail data for the Listing Designer theme and template (if either are used), which can optionally be used to enhance the appearance of the description area of an item's description. See ListingDesignerType for its child elements. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.ListingDesigner.LayoutID |
int | Optional | Identifies the Layout template to use when displaying the item's description. Call GetDescriptionTemplates for valid IDs. Set to false in GetDescriptionTemplates (or do not specify LayoutID) to get the standard layout. If a Listing Designer layout is used (except standard layout), PhotoDisplayType must be false (or not be specified). When relisting an item, LayoutID is removed from the listing if you specify ListingDesignerType without LayoutID. Alternatively, to remove this value when revising or relisting an item, use DeletedField. |
|
GetRecommendationsRequestContainer .Item.ListingDesigner .OptimalPictureSize |
boolean | Optional | If true, indicates that the item's picture will be enlarged to fit description of the item. |
|
GetRecommendationsRequestContainer .Item.ListingDesigner.ThemeID |
int | Optional | ID for the Listing Designer theme template to use when displaying the item's description. When relisting, if you specify ListingDesignerType without ThemeID, ThemeID is removed from the listing. Alternatively, to remove this value when revising or relisting an item, use DeletedField. |
|
GetRecommendationsRequestContainer .Item.ListingDetails |
ListingDetailsType | Optional |
Various details about a listing, some of which are calculated or derived after the item is listed. These include the start and end time, converted (localized) prices, and certain flags that indicate whether the seller specified fields whose values are not visible to the requesting user. For GetMyeBayBuying, returned as a self-closed element if no listings meet the request criteria. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.ListingDetails .LocalListingDistance |
string | Conditional | Specifies a distance (in miles) used as the radius of the area about the supplied postal code that constitutes the local market. Use GetCategoryFeatures to determine the local listing distances supported by a given site, category, and Local Market subscription level. |
|
GetRecommendationsRequestContainer .Item.ListingDetails .MinimumBestOfferMessage |
string | Optional |
Deprecated as of version 547. Currently ignored. Specifies the message sent from the seller to the buyer when a submitted best offer is automatically declined by the seller. A best offer is automatically declined if it does not meet the minimum acceptable best offer price specified by the seller with MinimumBestOfferPrice. Applies only to items listed in categories that support the Best Offer Auto-Decline feature. Best Offer must be enabled for the item. To remove this value when revising or relisting an item, use DeletedField. Deprecation version: 547. See also Deprecated Objects. |
|
GetRecommendationsRequestContainer .Item.ListingDetails .MinimumBestOfferPrice |
AmountType (double) | Optional | Specifies the minimum acceptable best offer price. If a buyer submits a best offer that is below this value, the offer is automatically declined by the seller. Applies only to items listed in categories that support the Best Offer Auto-Decline feature. Best Offer must be enabled for the item, and only the seller who listed the item can see this value. To remove this value when revising or relisting an item, use DeletedField. |
|
GetRecommendationsRequestContainer .Item.ListingDuration |
token | Optional |
Describes the number of days the seller wants the listing to be active (available for bidding/buying). The duration specifies the seller's initial intent at listing time. The end time for a listing is calculated by adding the duration to the item's start time. If the listing ends early, the value of the listing duration does not change. When a listing's duration is changed, any related fees (e.g., 10-day fee) may be debited or credited (as applicable). The valid choice of values depends on the listing format (see Item.ListingType). For a list of valid values, call GetCategoryFeatures with DetailLevel set to ReturnAll and look for ListingDurations information. When you revise a listing, the duration cannot be reduced if it will result in ending the listing within 24 hours of the current date-time. You are only allowed to increase the duration of the listing if fewer than 2 hours have passed since you initially listed the item and the listing has no bids. You can decrease the value of this field only if the listing has no bids (or no items have sold) and the listing does not end within 12 hours. Required for Half.com (but only specify GTC). See:
Applicable values: See ListingDurationCodeType |
|
GetRecommendationsRequestContainer .Item.ListingEnhancement |
ListingEnhancementsCodeType | Optional,
repeatable: [0..*] |
Describes listing upgrades that sellers can select for a fee, such as the BoldTitle upgrade. Also includes feature packs for saving on listing upgrades. See Listing Upgrades in the eBay Web site online help. You cannot remove listing upgrades when you revise a listing. When you relist an item, use DeletedField to remove a listing upgrades. Not applicable to Half.com. Applicable values: • BasicUpgradePackBundle (in/out) No longer applicable to any site. Formerly, a feature pack applicable to the Australia site (site ID 15, abbreviation AU) only. Contained the Gallery and Subtitle features. • BoldTitle (in/out) If specified, the seller wants the title for the item's listing to be in boldface type. Applicable listing fees apply. Does not affect the item subtitle (Item.SubTitle), if any. Not applicable to eBay Motors. • Border (in/out) If specified, the seller wants the item to be displayed with a border that goes around the item in search result pages that return multiple items. The border differentiates the item from other items in the list. Applicable listing fees apply. • CustomCode (in/out) Reserved for internal or future use. • Featured (in/out) Listing is a "Featured Plus" item. The item will display prominently in the Featured Items section of its category list, and it will stand out on search results pages. It will also display in the regular, non- featured item list. Only available to users with a Feedback rating of 10 or greater. • Highlight (in/out) Listing is highlighted in a different color in lists. • HomePageFeatured (in/out) Listing will have a chance to rotate into a special display on eBay's Home page. Your item is very likely to show up on the Home page, although eBay does not guarantee that your item will be highlighted in this way. This is the highest level of visibility on eBay. • ProPackBundle (in/out) Listing is using ProPackBundle (a feature pack). Applies only to US and Canadian eBay motor vehicle sellers, except in the US eBay Motors Parts and Accessories category. Contains the BoldTitle, Border, Featured and Highlight features. • ProPackPlusBundle (in/out) Support for this feature varies by site and category. A ProPackPlusBundle listing is using ProPackPlus bundle (a feature pack), which combines the features of BoldTitle, Border, Highlight, Featured (which is equivalent to a GalleryType value of Featured), and Gallery, for a discounted price. Note that if, for example, in AddItem, if you use ProPackPlusBundle and a GalleryType value of Gallery, then the resulting item will have a GalleryType value of Featured. • ValuePackBundle (in/out) Listing is using ValuePack bundle (a feature pack), which combines the features Gallery, Subtitle, and Listing Designer for a discounted price. Support for this feature varies by site and category. |
|
GetRecommendationsRequestContainer .Item.ListingType |
ListingTypeCodeType | Conditional |
The format of the listing the seller wants to use, such as auction style or fixed price. Optional for eBay.com listings (defaults to auction style) in AddItem and VerifyAddItem. Do not specify ListingType for eBay.com listings in ReviseItem. (You can't modify the listing type of an active eBay listing. Required for Half.com listings (and the value must be Half) in AddItem, VerifyAddItem, and ReviseItem. If you don't specify Half when revising Half.com listings, ReviseItem won't use the correct logic and you may get strange errors (or unwanted side effects in the listing, even if no errors are returned). Applicable values: • AdType (in/out) Advertisement to solicit inquiries on listings such as real estate. Permits no bidding on that item, service, or property. To express interest, a buyer fills out a contact form that eBay forwards to the the seller as a lead. This format does not enable buyers and sellers to transact online through eBay, and eBay Feedback is not available for ad format listings. • Chinese (in/out) Single-quantity online auction format. A Chinese auction has a Quantity of 1. Buyers engage in competitive bidding, although Buy It Now may be offered as long as no bids have been placed. Online auctions are listed on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • CustomCode (in/out) Reserved for internal or future use. • Dutch Deprecated as of version 611.
• Express Deprecated as of version 561.
• FixedPriceItem (in/out) A basic fixed-price item format. Bids do not occur. The quantity of items is one or more. • Half (in/out) Half.com listing (item is listed on Half.com, not on eBay). You must be a registered Half.com seller to use this format. • LeadGeneration (in/out) Lead Generation format (advertisement-style listing to solicit inquiries or offers, no bidding or fixed price, listed on eBay). • StoresFixedPrice (in/out) This enumeration value should no longer be used in the Add/Revise/Relist family of calls. The FixedPriceItem listing type replaced the StoresFixedPrice listing type on all eBay sites on March 30, 2010. (Not all values in ListingTypeCodeType apply to this field.) See:
|
|
GetRecommendationsRequestContainer .Item.Location |
string | Conditional |
Indicates the geographical location of the item (along with Country). When you revise a listing, you can add or change this value only if the listing has no bids (or no items have sold) and it does not end within 12 hours. If you do not specify Location, you must specify Item.PostalCode. If you specify a postal code, but do not specify a location, then the location is given a default value derived from the postal code. For the Classified Ad format for eBay Motors vehicles, the value provided in the Location is used as item location only if the SellerContactDetails.Street and the SellerContactDetails.Street2 are empty. Else, the SellerContactDetails.Street and the SellerContactDetails.Street2 will be used for item location. Also applicable as input to AddItem and related calls when you list items to Half.com. Max length: 45. |
|
GetRecommendationsRequestContainer .Item.LookupAttributeArray |
LookupAttributeArrayType | Optional |
No longer recommended. Call GetCategoryFeatures to see if the category you're listing in supports ConditionID. If it does, then use ConditionID instead of LookupAttributeArray. LookupAttributeArray was previously used as a shortcut for specifying the Condition attribute by name instead of by ID in categories that support product details (catalog-enabled categories). Typically only used in combination with ProductListingDetails. Note: If a category supports ConditionID, and you pass your item condition in LookupAttributeArray, eBay will not convert it to ConditionID, and your requests may fail if you specify the item condition in LookupAttributeArray. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.LookupAttributeArray .LookupAttribute |
LookupAttributeType | Optional,
repeatable: [0..*] |
The condition of the item. When catalog-enabled categories start supporting the newer ConditionID field in production, use ConditionID instead of LookupAttribute. |
|
GetRecommendationsRequestContainer .Item.LookupAttributeArray .LookupAttribute.Name |
string | Optional |
The literal name of the attribute. For the US site, pass "Condition" (without quotes). When catalog-enabled categories start supporting the newer ConditionID field in production, use ConditionID instead of LookupAttribute.Name. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.LookupAttributeArray .LookupAttribute.Value |
string | Optional |
The attribute's literal value (i.e., not the value ID), as it is returned in GetAttributesCS. For this US site, this could be a literal like "Brand New" (without quotes) for a book or "New, Never Opened" for a camera. The value is not case-sensitive, but all spaces and punctuation need to match the attribute's literal value. Not applicable to Half.com. eBay uses this value to set the correct attribute ID and value ID on the item. This means you need to specify the correct value for the primary category (which is either the category you specify in PrimaryCategory or the category that eBay sets based on the product you identify in ProductListingDetails or ExternalProductID. In GetItem, the attribute-based condition value is returned in AttributeSetArray. When catalog-enabled categories start supporting the newer ConditionID model in production, use ConditionID instead of LookupAttribute.Value. |
|
GetRecommendationsRequestContainer .Item.LotSize |
int | Optional |
A lot is a set of two or more similar items included in a single listing that must be purchased together in a single order line item. The Item.LotSize value is the number of items in the lot. This field is required if two or more items are including in one listing. Lots can be used for auction and fixed price listings. Lot items can be listed only in lot-enabled categories. Call GetCategories to determine if a category supports lots. If the returned CategoryArray.Category.LSD (LotSize Disabled) value is true, the category does not support lots. Not applicable to Half.com. Max: 100000. |
|
GetRecommendationsRequestContainer .Item.MotorsGermanySearchable |
boolean | Optional |
Listing upgrade that features the item in eBay search results on the mobile.de partner site. Applicable to eBay Germany. If true in listing requests and responses, the seller is purchasing or has purchased cross-promotional placement on the mobile.de site. See the Trading API Guide for applicable categories, revise and relist rules, and additional information on featuring vehicles on the Mobile.de Site. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.PaymentDetails |
PaymentDetailsType | Optional |
Contains data associated with eBay Motors payments and deposits. Applicable to US eBay Motors Vehicles. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.PaymentDetails .DaysToFullPayment |
int | Optional |
Applies to vehicle categories on the US and Canada eBay Motors sites (not Parts and Accessories categories). Number of days after a listing closes that the buyer can take to pay the full cost of the vehicle. The choices are 3, 7, 10, and 14, and the default is 7. PayPal and credit cards cannot be used to pay the full cost of a vehicle, so the listing must offer MOCC (cashier's check), PersonalCheck, LoanCheck, CashInPerson, and/or PaymentSeeDescription as payment methods. Min: 3. Max: 14. Default: 7. |
|
GetRecommendationsRequestContainer .Item.PaymentDetails .DepositAmount |
AmountType (double) | Conditional |
Applies to the US eBay Motors site (except the Parts and Accessories category). Specifies the amount of a vehicle deposit (a non-zero value up to $2000.00). If specified, then also specify HoursToDeposit and DepositType. This replaces the older US eBay Motors deposit amount attribute (attribute ID 10733). When you require a vehicle deposit, the won listing displays an option (such as a Pay button) to enable the buyer to pay the deposit online. Deposits can only be paid using PayPal, so if DepositAmount is specified, then listing must offer PayPal as a payment method (in addition to the payment methods offered for the full payment). Unlike other listings, PayPal is not automatically added to a Motors listing even if the seller has a PayPal preference set in My eBay. The seller also needs to have a linked PayPal account in order to specify a deposit. If a vehicle listing offers PayPal or a credit card, then the listing must also specify a deposit (because PayPal and credit cards cannot be used for full vehicle payments). Appears in shipping, payment details and return policy section of the View Item page. For ReviseItem and related calls: If the listing has no bids, the seller can add or lower a deposit; and they can increase the deposit if the listing doesn't require Immediate Payment. The seller can also remove the Immediate Payment option (if any). If the listing has bids, the seller can only lower an existing deposit; but not add or increase a deposit. The seller can't remove Immediate Payment when a listing with a deposit has bids. Min: 0.00. Max: 2000.00. Default: 0.0. |
|
GetRecommendationsRequestContainer .Item.PaymentDetails .DepositType |
DepositTypeCodeType | Conditional |
Applies to the US eBay Motors site (except the Parts and Accessories category). Deposit Type should be OtherMethod if DepositAmount is specified. Otherwise, specify None (or don't pass in DepositType). Deposits can only be paid using PayPal, so the listing must also offer PayPal as a payment method (in addition to the payment methods offered for the full payment). This replaces the older US eBay Motors deposit type attribute (attribute ID 10734). Appears in shipping, payment details and return policy section of the View Item page. Default: None. Applicable values: • CustomCode (in/out) Reserved for internal or future use • FastDeposit (in/out) No longer used. • None (in/out) No deposit needed. • OtherMethod (in/out) Pay the deposit using PayPal, and then use any of the other specified payment methods to pay the balance. |
|
GetRecommendationsRequestContainer .Item.PaymentDetails .HoursToDeposit |
int | Optional |
Applies to US eBay Motors site (except Parts and Accessories category). Number of hours after a listing closes that the buyer can put down a deposit on an item (if the seller specified a deposit). Only takes effect if listing also includes the Deposit Amount and Deposit Type attributes (see AttributeSetArray). The choices are 24, 48, and 72, and the default is 48. Deposits can only be paid using PayPal, so the listing must offer PayPal as a payment method (in addition to the payment methods offered for the full payment). Min: 24. Max: 72. Default: 48. |
|
GetRecommendationsRequestContainer .Item.PaymentMethods |
BuyerPaymentMethodCodeType | Conditional,
repeatable: [0..*] |
Identifies the payment method (such as PayPal) that the seller will accept when the buyer pays for the item. For the AddItem family of calls, at least one payment method is required. Use GetCategoryFeatures to determine the payment methods that are allowed for a category on a site. For example, the response data of GetCategoryFeatures will show that on the US site, most categories only allow electronic payments. Also use GetCategoryFeatures to determine the default payment method for a site (see SiteDefaults.PaymentMethod). If a seller does not include at least one payment method in a Add/Revise/RelistItem API call, the default payment method is used for the listing. Do not use GeteBayDetails to determine the payment methods for a site. For a DE or AT seller's items that are subject to the new eBay payment process, only one PaymentMethod field will be returned, and the value will always be 'StandardPayment'. As of August 2011, new sellers listing on the German (DE) or Austrian (AT) sites are subject to the new eBay payment process, and beginning May 2012 all sellers listing on the DE or AT sites are subject to the new eBay payment process.. If you specify multiple PaymentMethods fields, the repeating fields must be contiguous. For example, you can specify PayPalEmailAddress after a list of repeating PaymentMethods fields, but not between them: <PaymentMethods>VisaMC</PaymentMethods> <PaymentMethods>PayPal</PaymentMethods> <PayPalEmailAddress>mypaypalemail@ebay.com</PayPalEmailAddress> In general, if you separate repeating instances of a field, the results will be unpredictable. This rule applies to all repeating fields (maxOccurs="unbounded" or greater than 1) in the schema. See "Overview of the Schema" in the Trading API Guide. Note: Required or allowed payment methods vary by site and category. Refer to Payment Method Differences (PaymentMethod) in the eBay Trading API Guide for information to help you determine which payment methods you are required or allowed to specify. This field is not applicable to eBay Real Estate Ad format, Classified Ad format, or Half.com listings. For ReviseItem and RelistItem only: A listing must have at least one valid payment method. When you revise or relist an item and you specify a payment method that is invalid for the target site, eBay ignores the invalid payment method, applies the other valid changes, and returns a warning to indicate that the invalid payment method was ignored. If multiple payment methods were invalid, the warning indicates that they were all ignored. If you modify the listing so that it includes no valid payment methods, an error is returned. This situation could occur when the seller removes all valid payment methods or when all the payment methods specified for the item are no longer valid on the target site. For GetProducts only: Only PayPal is returned in product search results. Applicable values: See PaymentMethods. See:
|
|
GetRecommendationsRequestContainer .Item.PayPalEmailAddress |
string | Conditional |
Valid PayPal email address for the PayPal account that the seller will use if they offer PayPal as a payment method for the listing. eBay uses this to identify the correct PayPal account when the buyer pays via PayPal during the checkout process. (As a seller can have more than one PayPal account, you cannot necessarily rely on PayPal account data returned from GetUser for details about the account associated with the PayPal email address that the seller specifies.) Required if seller has chosen PayPal as a payment method (PaymentMethods) for the listing. For digital listings, the seller needs to use an email address that is associated with a PayPal Premier or PayPal business account. For ReviseItem and RelistItem only: To remove this value when you revise or relist an item, use DeletedField. When you revise a listing, if the listing has bids (or items have been sold) or it ends within 12 hours, you can add PayPalEmailAddress, but you cannot remove it. Not applicable to eBay Motors listings. Not applicable to Half.com. See:
|
|
GetRecommendationsRequestContainer .Item.PictureDetails |
PictureDetailsType | Optional |
Contains the data for a picture associated with an item. Not applicable to Half.com. Note: PictureDetails replaces the deprecated SiteHostedPicture and VendorHostedPicture in the response with request version 439 or greater. As SiteHostedPicture and VendorHostedPicture are also no longer recommended on input, applications should use PictureDetails in the input as well. If SiteHostedPicture or VendorHostedPicture are passed in with PictureDetails, PictureDetails takes precedence. |
|
GetRecommendationsRequestContainer .Item.PictureDetails .GalleryType |
GalleryTypeCodeType | Conditional |
Indicates whether listing images are included in the search results (in the Picture Gallery and List Views) and, if so, which enhancements apply. Items that have pictures but no image-listing enhancements have a generic photo image in search results, but see the information below about sites with free Gallery. If the GalleryType value is Gallery, Plus, or Featured, eBay checks the available image URLs in the following order to determine which URL to use (if more than one of these URLs is available): a) Use the URL in GalleryURL, if it is specified. b) Otherwise, if ProductListingDetails.UseStockPhotoURLAsGallery is true, use the eBay stock photo. c) Otherwise, use the value of the first PictureURL in the array of PictureURL fields, if any. d) Otherwise, if ProductListingDetails.ProductID is specified, use the eBay stock photo for that ProductID (eBay resets UseStockPhotoURLAsGallery to true in this case). e) If eBay cannot find an image URL for the listing, an error is returned. Note that you can use the Gallery Plus feature whether or not the image is hosted with eBay Picture Services (EPS). Selecting Gallery Plus does not incur a separate Gallery fee. See "Describing Items in a Listing" in the eBay Web Services Guide for additional information about working with pictures and related validation rules. You cannot remove Gallery, Plus, or Featured when revising an item, however you can upgrade to a higher feature. On upgrade, the original feature fee is credited, and the new feature fee is charged. There are a number of categories on some eBay sites that always offer the Gallery feature for free. (The API doesn't flag these categories in any meta-data calls.) In these categories, if you specify a picture and you don't specify GalleryType, eBay may add GalleryType=Gallery to the listing (for free) and return a warning (error code 219243). The Knowledge Base explains an edge case that could result in an unexpected gallery fee if the seller moves the item to a category that doesn't offer the free gallery feature. This fee can also appear when if the seller moves the item from a site that offers free Gallery (across all its categories) to one where free Gallery is not yet available. Whenever you change the primary category, it is a good idea to clearly specify whether the seller is intentionally requesting the gallery option. Note: The following sites offer free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146). On these sites, eBay will automatically create a Gallery thumbnail for the listing in search results by selecting a picture from one of the image URLs specified in the request (either Item.PictureDetails.PictureURL or Item.PictureDetails.GalleryURL) or from an available stock photo. Thus, a Gallery thumbnail will be created whenever Item.PictureDetails.GalleryType is None or is not specified in the request. A Gallery fee will apply whenever GalleryType specifies the Plus or Featured image enhancements (there will be no Gallery fee whenever GalleryType is Gallery, None or is not specified in the request). eBay will select the image for the thumbnail depending on which of the image URLs above was specified in the request (there are selection rules for four cases). Note that the selected image will not necessarily be the image you have specified in Item.PictureDetails.GalleryURL. Note that a Gallery thumbnail will not be automatically created if PictureURL and GalleryURL are not supplied and UseStockPhotoURLAsGallery and IncludeStockURL are set to false. The most common case occurs when both GalleryURL and PictureURL are specified in the request. eBay will use the image referenced by PictureURL as the Gallery thumbnail. As three other cases exist, please refer to "Using Gallery Features on Sites with Free Gallery" in the eBay Web Services Guide for complete information on how eBay selects an image for the gallery thumbnail on these sites. You cannot remove Gallery or Featured when revising an item, however you can upgrade to a higher feature. On upgrade, the original feature fee is credited, and the new feature fee is charged. (This does not apply to Gallery Plus on sites with free Gallery; see Plus below for more information.) Applicable values: • CustomCode (in/out) Reserved for internal or future use. • Featured (in/out) Highlights the listing at the top of the search results. (No longer available for the US site; also, no longer available on the US eBay Motors site, in the Parts and Accessories category. In these cases, listings containing Featured First are listed, but Featured First is dropped and a warning is returned.) • Gallery (in/out) Listing image is included in the search results (in both Picture Gallery and List Views). Items that have pictures but do not have the Gallery feature will have a generic photo image shown in search results. • None (in/out) Listing image is not included in the search results (in either Picture Gallery or List Views), and no other image listing enhancements apply. Items that have pictures but do not have image listing enhancements display a generic photo image in search results. • Plus (in/out) Listing image has Gallery Plus funtionality. That is, listing includes a Gallery Plus icon that, when moused over or clicked, displays a large (400 px x 400 px) preview image of the item. Clicking the image displays the View Item page for that listing. See:
|
|
GetRecommendationsRequestContainer .Item.PictureDetails .GalleryURL |
anyURI | Conditional |
Supported in Production only (not Sandbox). The URL for a picture used as the Gallery thumbnail. On a free-Gallery site, if there is a PictureURL, the PictureURL fills in or replaces the GalleryURL. Note that GalleryURL is ignored if GalleryType is None or unspecified. If the value of GalleryType is Gallery or Featured, you can either specify GalleryURL or allow eBay to use another picture that you have included in the listing. Note: The following sites offer free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146). On these sites, eBay selects a Gallery thumbnail from image URLs included in the request (i.e. either GalleryURL or the first PictureURL), using selection rules that consider which of these URLs was specified and whether an eBay stock photo exists for the item. Note that the selected gallery thumbnail may not necessarily be the one you specify using GalleryURL. Also, eBay selects an image regardless of whether you have specified either GalleryType or GalleryURL. A stock photo will not be generated for an item unless UseStockPhotoURLAsGallery and IncludeStockPhotoURL are set to true. Therefore, in this case, an item that does not have a PictureURL will not have a Gallery picture. A Gallery fee will only apply if you have set GalleryType to Plus or Featured (as basic Gallery is free). For more information on eBay's selection rules for the gallery thumbnail on sites with free Gallery, see "Using Gallery Features on Sites with Free Gallery" in the eBay Web Services Guide. (See GalleryType for the rules that determine which URL is used if you do not specify GalleryURL on sites where free Gallery is currently not available.) The image used for the Gallery thumbnail must be in one of the graphics formats JPEG, BMP, TIF, or GIF. See "Describing Items in a Listing" in the eBay Web Services Guide for additional validation rules. To remove GalleryURL when revising or relisting an item, use DeletedField. When you revise an item, you can only remove GalleryURL if the item has at least one PictureURL or a stock photo to use instead. If the item has bids (or items have been sold) or the listing ends within 12 hours, you can add GalleryURL or change its value, but you cannot remove the gallery URL value if it was previously specified. Not applicable to eBay Motors listings. Note: If a URI contains spaces, replace them with %20. For example, http://example.com/my image.jpg must be submitted as http://example.com/my%20image.jpg to replace the space in the image file name. Max length: 1024. See:
|
|
GetRecommendationsRequestContainer .Item.PictureDetails .PhotoDisplay |
PhotoDisplayCodeType | Conditional |
Specifies the type of image display used in a listing. Some options are only available if images are hosted through eBay Picture Services (EPS). eBay determines this by parsing the associated PictureURL. You cannot use PhotoDisplay in combination with Listing Designer layouts. Specify None or do not add PhotoDisplay when ListingDesigner.LayoutID is a value other than 0. Some PhotoDisplay options can result in listing fees, even when the item is relisted. If you are relisting an item that was originally listed with a PhotoDisplay option, and you do not want that PhotoDisplay enhancement in your relisted item, you need to specifically remove PhotoDisplay in your RelistItem call (or RelistFixedPriceItem, as applicable) by setting PhotoDisplay to None. Use VerifyRelistItem to review your listing fees before you relist an item. Applicable values: • CustomCode (in/out) Reserved for internal or future use. • None (in/out) No special image display options. Valid for US Motors listings. • PicturePack (in/out) Increase the number of images displayed. Only available for images hosted with eBay. See GetCategoryFeatures and the online Help (on the eBay site) for additional information. Picture Pack applies to all sites (including US Motors), except for NL (site ID 146). You can specify a minimum of one EPS picture, or no SuperSize-qualified EPS pictures in the request. For the NL site, PicturePack is replaced with SuperSize. • SiteHostedPictureShow (in/out) This value is no longer applicable. Formerly, the value displays multiple, site-hosted pictures in a slideshow format. • SuperSize (in/out) Increase the size of each image and allow buyers to enlarge images further. Only available for site-hosted (EPS) images. Not valid for US Motors listings. For all sites that do not automatically upgrade SuperSize to PicturePack (see note below), specifying no SuperSize-qualified images is now accepted in the request. • SuperSizePictureShow (in/out) This value is no longer applicable. Use SuperSize instead. Formerly, the value displays multiple, super-size, site-hosted pictures in a slideshow format. Valid for US Motors listings. • VendorHostedPictureShow (in/out) This value is no longer applicable. Formerly, the value displays multiple, vendor-hosted pictures in a slideshow format. Not valid for US Motors listings. (Not all values in PhotoDisplayCodeType apply to this field.) See:
|
|
GetRecommendationsRequestContainer .Item.PictureDetails .PictureURL |
anyURI | Conditional,
repeatable: [0..*] |
Contains a URL for a picture associated with an item; cannot be empty or null. The picture may be hosted on eBay Picture Services (EPS). Some options require hosting through EPS. Alternatively, the picture may be self-hosted. eBay determines where the picture is hosted by parsing the value specified in the request. On sites with free gallery, if a listing uses a self-hosted picture (except in the case of a multi-variation listing), the picture will be copied to EPS. The PictureDetails.PictureURL value returned by GetItem will be an EPS URL. See ExternalPictureURL above and see the link below titled "Copy of a Self-Hosted Picture To eBay Picture Services." On a free-Gallery site, if there is a PictureURL, the PictureURL fills in or replaces the GalleryURL. Note: The following sites have free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146). On free-gallery sites, eBay selects a Gallery thumbnail from picture URLs in the request (i.e., either the GalleryURL or the first PictureURL), with selection rules that consider which URLs were specified and whether an eBay stock photo exists for the item. eBay selects a picture regardless of whether you specified GalleryType or GalleryURL. Note that a stock photo is not generated unless the following are true: UseStockPhotoURLAsGallery and IncludeStockPhotoURL. Therefore, an item that does not have a PictureURL may have no Gallery picture. Note that a Gallery fee applies only if you set GalleryType to Plus or Featured (as basic Gallery is free). As a result of these changes, under certain scenarios the picture at the top of a listing may not be the picture you specified in PictureURL. For information about selection rules for the gallery thumbnail on sites with free Gallery, see "Using Gallery Features on Sites with Free Gallery" in the eBay Web Services Guide. To specify multiple pictures, send each URL in a separate, adjacent PictureURL element. In most cases, the picture at the first URL is also used for the picture at the top of a listing. Note: If a URI contains spaces, replace them with %20. For example, http://example.com/my image.jpg must be submitted as http://example.com/my%20image.jpg to replace the space in the image file name. On the main eBay site, a listing can have up to 12 EPS-hosted pictures, or one self-hosted picture. You cannot mix self-hosted and EPS-hosted pictures in one listing. On the US eBay Motors site (for all vehicle listings), and on the eBay Canada site for motors, the picture pack of a listing can contain up to 24 pictures. If you embed pictures in the description (with IMG tags) instead of using PictureURL, but you want a camera icon to appear in the search and listing pages, specify the following "clear picture" URL in PictureURL: http://pics.ebay.com/aw/pics/dot_clear.gif. Note: On free-gallery sites, the camera icon doesn't display as a gallery thumbnail (or on a listing page) when the first PictureURL field in the request is set to the "clear picture" URL; instead, eBay tries to use the picture referenced by GalleryURL as the gallery thumbnail. If GalleryURL has not been specified, a blank (camera-less) gallery thumbnail displays in the search results and at the top of the listing page. If you set the first PictureURL to the "clear picture" URL, you can specify Item.ProductListingDetails.UseStockPhotoURLAsGallery or Item.ProductListingDetails.UseStockPhotoURL to true, and eBay will use a stock photo, if available, for the gallery thumbnail and for the picture at the top of a listing. Note that a gallery picture isn't generated if UseStockPhotoURLAsGallery and IncludeStockPhotoURL are set to false (or not set) and no alternative picture is in PictureURL. A Gallery fee applies only if you have specified GalleryType as either Plus or Featured (see Item.PictureDetails.GalleryType above for information). See "Using Gallery Features on Sites with Free Gallery" in the eBay Web Services Guide for information on eBay's selection rules for Gallery pictures on sites with free Gallery. For VerifyAddItem only: For VerifyAddItem, you can use the following fake eBay Picture Services URL (http://i2.ebayimg.com/abc/M28/dummy.jpg) to verify that your application is obtaining the correct fees for the quantity of pictures you pass in. For ReviseItem and RelistItem only: To remove a picture when revising or relisting an item, specify PictureDetails with all the pictures that you want the listing to include. That is, you need to completely replace the original set of URLs with the revised set. To remove all PictureURL fields from a listing, specify item.PictureDetails.PictureURL in DeletedField. However, please note that if the listing also includes a gallery picture that is based on the first picture in the listing, you may need to supply an alternate picture to use as the gallery picture if you delete all PictureURL fields. There are a number of categories on some eBay sites that always add the Gallery feature (for free) when you include a picture in the listing and you don't specify the Gallery feature yourself. See GalleryType for details about fees that could be charged if you change the category in these cases (or when revising a listing from a site with free gallery to one where free gallery is not yet available.) Max length: 150. See:
|
|
GetRecommendationsRequestContainer .Item.PostalCode |
string | Optional |
Postal code of the place where the item is located. This value is used for proximity searches. To remove this value when revising or relisting an item, use DeletedField. If you do not specify PostalCode, you must specify Item.Location. If you specify PostalCode, but do not specify Item.Location, then Item.Location is given a default value derived from the postal code. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.PrimaryCategory |
CategoryType | Required |
Category ID for the first (or only) category in which the item is listed (or will be listed, if the item is new). A number of listing features have dependencies on the primary category. We have pointed out a few of the notable dependencies below. See the descriptions of the fields you are using to determine whether the feature you're supporting depends on the listing's primary category. For the AddItem family of calls: Use calls like GetCategories and GetCategoryFeatures to determine valid values for the site on which you are listing (see the eBay Web Services Guide for information on working with categories). Also see Item.CategoryMappingAllowed and Item.CategoryBasedAttributesPrefill. There are a number of categories on some eBay sites that always add the Gallery feature (for free) when you include a picture in the listing and you don't specify the Gallery feature yourself. See GalleryType for information about fees that could be charged if you change the category in these cases. Coming soon: If you list with a catalog product, eBay may drop the primary category you specify and use the category that is associated with the product instead, if different. Not applicable to Half.com. For ReviseItem only: When revising a listing, you can change the primary category only if an item has no bids (or no items have sold) and the listing does not end within 12 hours. If you change the listing category, any Item Specifics (attributes) that were previously specified may be dropped from the listing if they aren't valid for the new category. See Item.AttributeSetArray. For the eBay US site, we suggest that you avoid including a category ID when you list with an external product ID, such as ISBN. See the KB article listed below for details. You cannot change the meta-categories for vehicles (i.e., you cannot change a truck to a motorcycle), but you can change the leaf category (e.g., change one motorcycle subcategory to another motorcycle subcategory). See the eBay Web Services Guide for additional rules. International sites (such as the eBay Germany site) have similar rules for revising vehicle categories. When you list an event ticket on the US site, you must specify the Event Tickets category as the primary category. Also, when revising a listing, you cannot change the primary category from another category to the Event Tickets category. (You need to specify the Event Tickets category when you initially list the item.) For GetItemRecommendations only: For GetItemRecommendations, use this value to control the category that is searched for recommendations. Specify the category in which the item will be listed. See Getting Recommendations to Improve a Listing in the eBay Web Services guide for differences in validation rules depending on whether you are using the Listing Analyzer engine, Product Pricing engine, or Suggested Attribute engine. For GetProducts: Use GetCategories if you need to determine the name of the category. See:
|
|
GetRecommendationsRequestContainer .Item.PrimaryCategory .CategoryID |
string | Required |
Distinct numeric ID for a category on eBay. In GetItem and related calls, see CategoryName for the text name of the category. Use GetCategories to look up the category parent ID. For GetPopularKeywords, -1 represents the root category. For GetItem, Half.com items return the Half.com category ID in PrimaryCategory. This ID is not necessarily returned in GetCategories. Max length: 10. |
|
GetRecommendationsRequestContainer .Item.PrivateListing |
boolean | Optional |
The PrivateListing boolean field can be used by the seller in the Add/Relist/Revise family of calls to obscure item title, item ID, and item price from post-order Feedback comments left by buyers. Typically, it is not advisable that sellers use the Private Listing feature, but using this feature may be appropriate for sellers listing in Adults Only categories, or for high-priced and/or celebrity items. For GetItem, order retrieval calls, and other calls that retrieve the Item object, the PrivateListing field is only returned if 'true'. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.PrivateNotes |
string | Optional |
A note a user makes on an item in their My eBay account. The note is prefaced with the words My Note. For eBay.com, only GetMyeBayBuying and GetMyeBaySelling (not GetItem) return this field, and only if you pass IncludeNotes in the request. Only visible to the user who created the note. Not supported as input in ReviseItem. Use SetUserNotes instead. For GetMyeBayBuying In WatchList, notes for variations are only returned at the Item level, not the variation level. They are only set if you specified ItemID (if no purchases) or ItemID and VariationSpecifics (if there are purchases) in SetUserNotes (or selected the equivalent in the My eBay UI on the site). In WonList, notes for variations are only returned at the Item level, not the variation level. They are only set if you specified ItemID and TransactionID in SetUserNotes (or selected the equivalent in the My eBay UI on the site). Not applicable to Half.com (instead, use Item.AttributeArray.Attribute.Value.ValueLiteral for Half.com notes.) |
|
GetRecommendationsRequestContainer .Item.ProductListingDetails |
ProductListingDetailsType | Conditional |
Specifies stock product information to include in a listing. Only applicable when listing items with product details. See the eBay Trading API Guide for information on listing with product details. As ProductID and ProductReferenceID are defined by eBay, they provide the most reliable means to identify a product. If you use ISBN, UPC, EAN, BrandMPN, and/or TicketListingDetails, eBay attempts to find a matching product on your behalf and use it in the listing. If no match is found, you can try using the catalog search calls (such as GetProductSearchResults or GetProducts) to find a ProductID or ProductReferenceID. When you specify ProductListingDetails, you must specify at least one product ID for the listing (ProductID, ProductReferenceID, ISBN, UPC, EAN, BrandMPN, and/or TicketListingDetails). If you specify more than one of these values (such as UPC and BrandMPN), eBay uses the first one that matches a product in eBay's catalog system. (This may be useful if you aren't sure which ID is more likely to result in a match.) When you specify TicketListingDetails, you must specify the Event Tickets category as the primary category. For other product ID: If you list in two categories and the primary and secondary categories are both catalog-enabled, this product should correspond to the primary category (not the secondary category). If only one category is catalog-enabled, the product listing details should correspond to the catalog-enabled category. (Use GetCategory2CS to determine which categories are catalog-enabled.) Note: As a general rule, the primary category is required. However, if you have trouble finding a catalog-enabled category, you may be able to omit the primary category (except for event tickets). If you do, eBay will attempt to determine an appropriate category based on the product ID (if we find a matching product). When you specify a category that corresponds to the product (according to GetCategory2CS), your category is used. If we don't find a match for a UPC, ISBN, or EAN in our catalogs, we will list the item in the primary category you specified, without product details. We will not pre-fill the listing's item specifics in this case, and the identifier won't be surfaced in View Item or returned in GetItem. However, it will still be indexed for search on eBay, and it will be searchable by more third-party natural search engines. As this can help buyers find your listing more easily, we strongly recommend that you always use ProductListingDetails to pass in these values. (This product indexing behavior is only available if you use UPC, ISBN, or EAN in ProductListingDetails. It is not available if you use ExternalProductID, and it may not be available if you exclusively use Item Specifics.) Either Item.ExternalProductID or Item.ProductListingDetails can be specified in an AddItem request, but not both. (ExternalProductID will be deprecated in a future release.) For ReviseItem and RelistItem only: If a listing includes product details and you change a category, the rules for continuing to include product details depend on whether or not the new category is mapped to a characteristic set associated with the same product ID. When you revise a listing, if it has bids or it ends within 12 hours, you cannot change the product ID and you cannot remove existing product data. However, you can change or add preferences such as IncludeStockPhotoURL, UseStockPhotoURLAsGallery, and IncludePrefilledItemInformation. To delete all catalog data when you revise or relist an item, specify Item.ProductListingDetails in DeletedField and don't pass ProductListingDetails in the request. For GetItemRecommendations only: For GetItemRecommendations, see the Trading API Guide for validation rule differences when using the Product Pricing engine. For GetMyeBayBuying only: When products have been added to a buyer's Wish List, the product information is returned in ItemArray.Item.ProductListingDetails within the UserDefinedList node. Products can be added to a buyer's Wish List only. Does not apply to any other user-defined list. The ProductListingDetails node is not included for items in the Wish List. Not applicable to Half.com. See:
|
|
GetRecommendationsRequestContainer .Item.ProductListingDetails .IncludePrefilledItemInformation |
boolean | Optional |
If true, specifies that the listing should include additional information about the product, such as a publisher's description or film credits. Such information is hosted through the eBay site and cannot be edited. If true, Item.Description is optional in item-listing requests. For GetItem and related calls: The eBay site shows the catalog product description in the product details section of a listing. You cannot download this pre-filled description text via the API. To retrieve a URL for the catalog product details page, see DetailsURL in GetProductSearchResults, GetProductFamilyMembers, or GetProductSellingPages. Or see DetailsURL in FindProducts in the Shopping API (which may be easier to use if your application doesn't support eBay Attributes). Default: true. |
|
GetRecommendationsRequestContainer .Item.ProductListingDetails .IncludeStockPhotoURL |
boolean | Optional |
If true, indicates that the item listing includes the stock photo. To use an eBay stock photo in an item listing, set IncludeStockPhotoURL to true. If a stock photo is available, it is used at the top of the View Item page and in the Item Specifics section of the listing. If you also include Item.PictureDetails.PictureURL, the stock photo only appears in the Item Specifics section of the listing. Other pictures you specify by using Item.PictureDetails.PictureURL appear in a separate section of the listing. If you use Item.ExternalProductID instead of Item.ProductListingDetails, eBay sets IncludeStockPhotoURL to true (and you cannot set it to false). In GetItem, the URL of the stock photo will be returned in StockPhotoURL. If you set IncludeStockPhotoURL to false, the stock photo does not appear in the listing at all. Note: The following sites offer free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146). On these sites, eBay selects a Gallery thumbnail from image URLs included in the request (i.e. either GalleryURL or the first PictureURL), using selection rules that consider which of these URLs has been specified and whether an eBay stock photo exists for the item. Also, eBay selects an image regardless of whether you have specified either GalleryType or GalleryURL. A Gallery fee will only apply if you have set GalleryType to Plus or Featured (as basic Gallery is free). Along with these changes, IncludeStockPhotoURL will be used in the request. In some cases, if IncludeStockPhotoURL is set to false, no image will be generated for the Gallery. A common example of this occurrence is when only GalleryURL has been set in the request (i.e., no PictureURL elements are defined). In this case, eBay will not use a stock photo, even if it is available. See "Using Gallery Features on Sites with Free Gallery" in the eBay Web Services Guide for complete information. Not applicable to Half.com. Default: true. See:
|
|
GetRecommendationsRequestContainer .Item.ProductListingDetails .ProductID |
string | Conditional |
eBay's unique identifier for a specific version of a product. This is the long alphanumeric ID that is returned from GetProductSearchResults and related calls. See the Trading API Guide for information about finding this type of product ID. (For the shorter product ID (ePID) value that is displayed on the eBay Web site, see ProductReferenceID instead.) If the primary and secondary categories are both catalog-enabled, this ID should correspond to the primary category (not the secondary category). In item-listing requests, if you pass in an old product ID, eBay lists the item with the latest version of the product and the latest product ID, and the call returns a warning indicating that the data has changed. Some sites (such as eBay US, Germany, Austria, and Switzerland) are updating, replacing, deleting, or merging some products (as a result of migrating from one catalog data provider to another). If you specify one of these products in a request, the call may return the product with a warning, or it may fail with an error if the product has been deleted. Max length: 4000. |
|
GetRecommendationsRequestContainer .Item.ProductListingDetails .ProductReferenceID |
string | Conditional |
eBay's short global reference ID for a catalog product. On the eBay Web site, this is known as the "ePID" or "Product ID". This type of product ID is a fixed reference to a product (regardless of version). Multiple (versioned) ProductID values can be associated with a single product reference ID. You can find product reference IDs for products by using GetProducts (or FindProducts in the Shopping API). You can also find the product ID on eBay's Web site (a numeric value prefixed with "EPID"). You can pass the value with or without the "EPID" prefix; for example "EPID228742" or "228742" (without quotes). If the primary and secondary categories are both catalog-enabled, this ID should correspond to the primary category (not the secondary category). Some sites (such as eBay US, Germany, Austria, and Switzerland) are updating, replacing, deleting, or merging some products (as a result of migrating from one catalog data provider to another). If you specify one of these products in a request, the call may return the product with a warning, or it may return an error if the product has been deleted. Max length: 38 (42 with "EPID"). |
|
GetRecommendationsRequestContainer .Item.ProductListingDetails .TicketListingDetails |
TicketListingDetailsType | Conditional |
Applicable for listing use cases only (not buy-side searching). Only applicable when you are listing event tickets. Please note that the US eBay site and other sites may also require you to specify additional Item Specifics by using AttributeSetArray. This may depend on the location of the event. See the eBay Trading API Guide for more information about how to specify and troubleshoot these values.
See:
|
|
GetRecommendationsRequestContainer .Item.ProductListingDetails .TicketListingDetails .PrintedTime |
string | Conditional |
The time of the event, as shown on the ticket. Use the time value shown on the ticket, without attempting to convert it to a different time zone (such as Pacific time or GMT). Do not round the value up or down (e.g., do not round 7:01 PM to 7:00 PM). In most cases, you should be able to specify the time format exactly as shown on the ticket. For a list of formats that have been tested, see the eBay Trading API Guide. See Pre-filling a Ticket Listing Based on Keywords (Name, Venue, and Date). |
|
GetRecommendationsRequestContainer .Item.ProductListingDetails .UseStockPhotoURLAsGallery |
boolean | Optional |
If true, indicates that the stock photo for an item (if available) is used as the gallery thumbnail. When listing an item, IncludeStockPhotoURL must also be true and Item.PictureDetails.GalleryType must be passed in with a value of Gallery or Gallery Featured (but not both). Passing in Item.PictureDetails.GalleryURL takes precedence over UseStockPhotoURLAsGallery. See the eBay Trading API guide for additional validation rules for pictures. Note: The following sites offer free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146). On these sites, eBay selects a Gallery thumbnail from image URLs included in the request (i.e. either GalleryURL or the first PictureURL), using selection rules that consider which of these URLs has been specified and whether an eBay stock photo exists for the item. Also, eBay selects an image regardless of whether you have specified either GalleryType or GalleryURL. A Gallery fee will only apply if you have set GalleryType to Plus or Featured (as basic Gallery is free). Along with these changes, UseStockPhotoURLAsGallery will be used in the request. In some cases, if UseStockPhotoURLAsGallery is set to false, no image will be generated for the Gallery. A common example of this occurrence is when only GalleryURL has been set in the request (i.e., no PictureURL elements are defined). In this case, eBay will not use a stock photo, even if it is available. See "Using Gallery Features on Sites with Free Gallery" in the eBay Web Services Guide for complete information. Default: true. See:
|
|
GetRecommendationsRequestContainer .Item.Quantity |
int | Optional |
Note: In late October 2010, for the US site, users who are registering as eBay sellers for the first time are subject to seller limits which limit the quantity of items and/or the total listing value of the items. This applies to new sellers, not currently to existing sellers. (The GetMyeBaySelling call returns the remaining item quantity and remaining total value under the limits for the seller, if any such limits exist for the seller.) If a call to add an item or revise an item would result in the exceeding of these limits, the add item or revise item call will fail. For auctions, the value limits apply to the start price, not the final sale amount. For more information, see the link to Seller Limits below. The meaning of this value depends on the context. For AddItem family of calls: The Quantity value for auction listings must always be 1. For a fixed-price listing, the Quantity value indicates the number of identical items the seller has available for sale in the listing. If variations are specified in AddFixedPriceItem or VerifyAddFixedPriceItem, the Item.Quantity is not required since the quantity of variations is specified in Variation.Quantity instead. See the Creating a listing with variations eBay Help page for more information on variations. For ReviseItem and ReviseFixedPriceItem: This value can only be changed for a fixed-price listing with no variations. The quantity of variations is controlled in the Variation.Quantity field and the Item.Quantity value for an auction-style listing should always be 1. For RelistItem and RelistFixedPriceItem: Like most fields, when you use RelistItem or RelistFixedPriceItem, Quantity retains its original value unless you specifically change it. This means that the item is relisted with the value that was already in Quantity, not with the remaining quantity available. For example, if the original Quantity value was 10, and 3 items have been sold, eBay sets the relisted item's Quantity to 10 by default, and not 7. So, we strongly recommend that you always set Quantity to the correct value (your actual quantity available) in your relist requests. When eBay auto-renews a GTC listing (ListingDuration=GTC) on your behalf, eBay relists with correct quantity available. For GetSellerEvents: Quantity is only returned for listings where item quantity is greater than 1. For GetItem and related calls: This is the total of the number of items available for sale plus the quantity already sold. To determine the number of items available, subtract SellingStatus.QuantitySold from this value. Even for items that supported Dutch auctions, where one of several items can be purchased during the auction, this number does not change. For order line item calls with variations: In GetItemTransactions, Item.Quantity is the same as GetItem (the total quantity across all variations). In GetSellerTransactions, Transaction.Item.Quantity is the total quantity of the applicable variation (quantity available plus quantity sold). For GetDispute: Quantity is the number of items being raised in the dispute. For SetCart input, this is only required if the parent container is submitted. Also applicable to Half.com (valid range 1 to 1000). You can revise this field for Half.com listings. Note: As of version 619, Dutch-style (multi-item) competitive-bid auctions are deprecated. eBay throws an error if you submit a Dutch item listing with AddItem or VerifyAddItem. If you use RelistItem to update a Dutch auction listing, eBay generates a warning and resets the Quantity value to 1. |
|
GetRecommendationsRequestContainer .Item.ReservePrice |
AmountType (double) | Optional |
The lowest price at which the seller is willing to sell the item. (StartPrice must be lower than ReservePrice.) Not all categories support a reserve price. See GetCategories and "Determining Whether a Category Supports Reserve Prices" in the Trading API Guide. In calls that retrieve item data, ReservePrice only has a non-zero value for listings with a reserve price and where the user requesting the item data is also the item's seller. Not applicable to fixed- price items or ad format listings. You can remove the reserve price of a US eBay Motors listing if the category allows it, the current reserve price has not been met, and the reserve price is at least $2.00 more than the current high bid. In this case, if the item has bids, the reserve price is set to $1.00 over the current high bid. The next bid meets the reserve and wins. See the Fees Overview on the eBay Web site for information about fee credits that may be available when the reserve price is removed for a Motors listing. See the Trading API Guide for validation rules when revising US Motors listings. If relisting an item, the seller must set the ReservePrice to a value equal or less than the value of of ReservePrice when the listing ended. If the ReservePrice is set higher than this value (such as the ReservePrice set when the item was first listed), an error will occur. Not applicable to Half.com. See:
|
|
GetRecommendationsRequestContainer .Item.ReturnPolicy |
ReturnPolicyType | Optional |
Container that describes the seller's return policy. Most categories on most eBay sites require the seller to include a return policy through the ReturnPolicy container. For the AddItem family of calls: Required for most categories on most sites. Use ReturnPolicyEnabled in GetCategoryFeatures to determine which categories require this field. Also use ReturnPolicyDetails in GeteBayDetails to determine which ReturnPolicy fields can be used on each site. eBay India (IN), Australia (AU), and US eBay Motors Parts and Accessories categories typically support but do not require a return policy. (However, we strongly recommend that you specify a clear return policy whenever possible.) For ReviseItem only: If the listing has bids or sales and it ends within 12 hours, you can't change the return policy details. If the listing is a GTC listing that has sales or ends within 12 hours (one or the other, but not both), you can add a return policy to the GTC listing (but you can't change return policy details if already present). If the listing has no bids or sales and more than 12 hours remain before the listing ends, you can add or change the return policy. When you revise your return policy, you only need to specify the fields you want to add or change. You don't need to specify all the other ReturnPolicy fields again. The other fields will retain their existing settings. For the GetItem family of calls: Only returned if the site you sent the request to supports the seller's return policy. Typically, the return policy details are only returned when the request is sent to the listing site. See:
|
|
GetRecommendationsRequestContainer .Item.ReturnPolicy.Description |
string | Optional |
A detailed explanation of the seller's return policy. eBay uses this text string as-is in the Return Policy section of the View Item page. Avoid HTML, and avoid character entity references (such as £ or £). If you include special characters in the return policy description, use the literal UTF-8 or ISO-8559-1 character (e.g. £). For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but does not specify this field when listing the item, GetItem returns this as an empty node For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. Max length: 5000. See (GeteBayDetails) ReturnPolicyDetails.Description for sites that support this field. |
|
GetRecommendationsRequestContainer .Item.ReturnPolicy.EAN |
string | Optional |
The European Article Number (EAN) associated with the item, if any. Refer to the ReturnPolicyDetails node in GeteBayDetails to determine which sites support this field. Only returned if the seller has specified this value in their return policy. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) ReturnPolicyDetails.EAN for sites that support this field. |
|
GetRecommendationsRequestContainer .Item.ReturnPolicy .RefundOption |
token | Optional |
Indicates how the seller will compensate the buyer for a returned item. Use the ReturnPolicy.Description field to explain the policy details (such as how quickly the seller will process the refund, whether the seller must receive the item before processing the refund, and other useful details.). Applicable values: Use GeteBayDetails to determine which sites support this field, and the applicable values for each site. (RefundOptionsCodeType defines all the possible values.) For AddItem, VerifyAddItem, and RelistItem (and corresponding FixedPrice calls): If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this RefundOption field when listing the item, some eBay sites may set a default value (like MoneyBack), and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. Note: Beginning with version 771, listings created, revised, or relisted with deprecated RefundOption and/or ReturnsWithinOption values (using Add/Revise/Relist family of API calls) will start being blocked. For RefundOption, the deprecated values are MerchandiseCredit and Exchange. Instead of these deprecated values, the seller must offer a MoneyBack or a MoneyBackOrExchange refund option. Consider using the MoneyBackOrExchange option when you have the depth of inventory to support an exchange for a different size, color, or undamaged unit. Otherwise, use the MoneyBack option if you have limited inventory. See (GeteBayDetails) RefundOption for sites that support this field, and applicable values. Applicable values: See RefundOptionsCodeType |
|
GetRecommendationsRequestContainer .Item.ReturnPolicy .ReturnsAcceptedOption |
token | Optional |
Indicates whether the seller allows the buyer to return the item. This field is required when ReturnPolicy is specified. (If you specify ReturnsNotAccepted, the View Item page may initially show the return policy as unspecified. In a future release, the View Item page will be updated to indicate that returns are not accepted instead.) All sites support the ability for a seller to not accept returns. If the seller doesn't accept returns, the item must specifically indicate ReturnsNotAccepted. (The return policy cannot be omitted from the item.) On the eBay UK and Ireland sites, business sellers must accept returns for fixed price items (including auction items with Buy It Now, and any other fixed price formats) when the category requires a return policy. On some European sites (such as eBay Germany (DE)), registered business sellers are required to accept returns. Your application can call GetUser to determine a user's current business seller status. Applicable values: Use GeteBayDetails to determine which sites support this field, and the applicable values for each site. (ReturnsAcceptedOptionsCodeType defines all the possible values.) For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See:
Applicable values: See ReturnsAcceptedOptionsCodeType |
|
GetRecommendationsRequestContainer .Item.ReturnPolicy .ReturnsWithinOption |
token | Conditional |
The buyer can return the item within this period of time from the day they receive the item. Use the ReturnPolicy.Description field to explain the policy details. Applicable values: Use GeteBayDetails to determine which sites support this field, and the applicable values for each site. (ReturnsWithinOptionsCodeType defines all the possible values.) For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this ReturnsWithinOption field when listing the item, some eBay sites may set a default value (like Days_14), and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. Note: Beginning with version 771, listings created, revised, or relisted with deprecated RefundOption and/or ReturnsWithinOption values (using Add/Revise/Relist family of API calls) will start being blocked. For ReturnsWithinOption, the deprecated values are Days_3 and Days_7. Instead of these deprecated values, the seller must offer a 14-day, 30-day, or 60-day return window. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) ReturnsWithinOption for sites that support this field, and applicable values. Applicable values: See ReturnsWithinOptionsCodeType |
|
GetRecommendationsRequestContainer .Item.ReturnPolicy .ShippingCostPaidByOption |
token | Optional |
The party who pays the shipping cost for a returned item. Use the ReturnPolicy.Description field to explain any additional details. Applicable values: Use GeteBayDetails to determine which sites support this field, and the applicable values for each site. (ShippingCostPaidByOptionsCodeType defines all the possible values.) For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this ShippingCostPaidByOption field when listing the item, some eBay sites may set a default value (like Buyer), and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) ShippingCostPaidByOption for sites that support this field, and applicable values. Applicable values: See ShippingCostPaidByOptionsCodeType |
|
GetRecommendationsRequestContainer .Item.ReturnPolicy .WarrantyDurationOption |
token | Optional |
The warranty period. Applicable values: Use GeteBayDetails to determine which sites support this field, and the applicable values for each site. (Initially, only the eBay India site supports this field.) (WarrantyDurationOptionsCodeType defines all the possible values.) For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this WarrantyDurationOption field when listing the item, the eBay India site may set a default value, and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) WarrantyDurationOption for sites that support this field, and applicable values. Applicable values: See WarrantyDurationOptionsCodeType |
|
GetRecommendationsRequestContainer .Item.ReturnPolicy .WarrantyOfferedOption |
token | Optional |
Indicates whether a warranty is offered for the item. Applicable values: Use GeteBayDetails to determine which sites support this field, and the applicable values for each site. (Initially, only the eBay India site supports this field.) (WarrantyOfferedCodeType defines all the possible values.) For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this WarrantyOfferedOption field when listing the item, the eBay India site may set a default value, and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. Note: For the US eBay Motors limited warranty (Short-Term Service Agreement) option, use Item.LimitedWarrantyEligible instead. For the US eBay Motors "Is There an Existing Warranty?" option, use Item.AttributeSetArray instead. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See:
Applicable values: See WarrantyOfferedCodeType |
|
GetRecommendationsRequestContainer .Item.ReturnPolicy .WarrantyTypeOption |
token | Optional |
Indicates the source or type of the warranty, if any. Applicable values: Use GeteBayDetails to determine which sites support this field, and the applicable values for each site. (Initially, only the eBay India site supports this field.) (WarrantyTypeOptionsCodeType defines all the possible values.) For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this WarrantyTypeOption field when listing the item, the eBay India site may set a default value, and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) WarrantyTypeOption for sites that support this field, and applicable values. Applicable values: See WarrantyTypeOptionsCodeType |
|
GetRecommendationsRequestContainer .Item.ScheduleTime |
dateTime | Optional |
Allows the user to specify the time that the listing becomes active on eBay. To schedule the listing start time, specify a time in the future in GMT format. In GetItem and related calls, the scheduled time is returned in StartTime. For ReviseItem, you can modify this value if the currently scheduled start time is in the future. When you schedule a start time, the start time is randomized within 15-minute intervals. Randomized start times applies to the following sites: AT, BEFR, BENL, CH, DE, ES, FR, IE, IT, NL, PL, UK Also see the following article in the Knowledge Base: Why scheduled time is sometimes getting reset. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.SecondaryCategory |
CategoryType | Optional |
ID for second category in which the item is listed (also see Item.PrimaryCategory). For the AddItem family of calls: Listing an item in a second category is optional. Also see Item.CategoryMappingAllowed and Item.CategoryBasedAttributesPrefill. Not applicable to Half.com. On the eBay UK, Ireland, Germany, Austria, Switzerland, and Italy sites you can list Store Inventory listings in two categories. On the eBay US and other sites, you cannot list Store Inventory listings in two categories. You cannot list US eBay Motors vehicles in two categories. However, you can list Parts & Accessories in two categories. The Final Value Fee is based on the primary category in which the item is listed. Furthermore, you can list the same item in an eBay Motors Parts & Accessories category and in an eligible eBay category, as long as the primary category is associated with the site on which you are listing. That is, the two categories can be a mix of Motors Parts & Accessories and eBay site categories. (Real Estate, Mature Audience (adult), and Business & Industrial categories are not eligible for listing in two categories in this manner.) For example, if you list on Motors, the primary category could be 6750 (eBay Motors > Parts & Accessories > Apparel & Merchandise > Motorcycle > Jackets & Leathers), and the secondary category could be 57988 (eBay > Clothing, Shoes > Accessories > Men's Clothing > Outerwear). If you list on the main eBay site, the primary category could be 57988 and the secondary category could be 6750. If eBay has designated a category as a value category (see ValueCategory in GetCategoryFeatures), items in that category cannot be listed in two categories. For example, if your AddItem request includes a primary or secondary category that is a value category, then eBay drops SecondaryCategory and lists the item with only the PrimaryCategory you selected. Also, if the listing request includes item specifics (in ItemSpecifics or AttributeSetArray) that are associated with SecondaryCategory, eBay drops those values when we drop SecondaryCategory. (The same logic is used if you revise an existing listing to add a secondary category or to change one of the categories: If either the primary or secondary category is a value category, eBay drops the secondary category from your request.) To remove this value when relisting an item, use DeletedField. For ReviseItem only: When revising a listing, you can add, remove, or change the secondary category only if the listing has no bids (or no items have sold) and it does not end within 12 hours. If you change the secondary category, any corresponding Item Specifics (attributes) that were previously specified may be dropped from the listing if they aren't valid for the category. See Item.AttributeSetArray. When you revise an item, you can change the secondary category from a Motors Parts & Accessories category to an eBay category or vice versa if the listing has no bids (or no items have sold) and it does not end within 12 hours. For GetItemRecommendations only: For GetItemRecommendations, use this to control the category that will be searched for recommendations. Specify the category in which the item will be listed. See the Trading API Guide for differences in validation rules depending on whether you are using the Listing Analyzer engine, Product Pricing engine, or Suggested Attributes engine. See Categories. |
|
GetRecommendationsRequestContainer .Item.SecondaryCategory .CategoryID |
string | Required |
Distinct numeric ID for a category on eBay. In GetItem and related calls, see CategoryName for the text name of the category. Use GetCategories to look up the category parent ID. For GetPopularKeywords, -1 represents the root category. For GetItem, Half.com items return the Half.com category ID in PrimaryCategory. This ID is not necessarily returned in GetCategories. Max length: 10. |
|
GetRecommendationsRequestContainer .Item.SellerInventoryID |
string | Optional |
Unique identifier for a Half.com item. Must be an alphanumeric value (with no symbols) that is unique across the seller's active (unsold) inventory on Half.com. For Half.com, you can specify either ItemID or SellerInventoryID in a ReviseItem request to uniquely identify the listing. Only returned from GetOrders if the seller specified a value when the item was listed. You cannot revise this field. Not applicable to eBay.com listings. Max length: 100. |
|
GetRecommendationsRequestContainer .Item.SellerProvidedTitle |
string | Optional |
A descriptive free-text title for a US or CA eBay Motors vehicle listing. This title appears below eBay's pre-filled listing title on the View Item page (not at the top of the View Item page). It's also appended to the listing title in search results (like a subtitle) on the US eBay Motors site. Keywords in this title help buyers find or distinguish your listing. Applicable to listings in US eBay Motors Cars and Trucks, Motorcycle, and some of the Powersport, Boats and RV campers categories; or to Cars and Trucks listings on CA eBay Motors. This replaces the older US and Canada eBay Motors Subtitle attribute (attribute ID 10246). Not applicable to Half.com. Max length: 80. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails |
ShippingDetailsType | Conditional |
The shipping-related details for an order, including flat and calculated shipping costs and shipping insurance costs. New users who list their first items in selected categories on the US site must specify at least one domestic shipping service. This applies to a category if GetCategoryFeatures returns true for Category.ShippingTermsRequired. For multi-quantity Store Inventory Format listings and for multi-quantity Fixed Price listings, a seller can revise all shipping details of the listing (except for sales tax and for shipping type of Freight) for all unsold items. This applies to both domestic and international shipping. Checkout is not affected for those who bought items prior to the seller's shipping changes--the shipping details that were in effect at the time of purchase are used for that buyer at the time of checkout. Shipping details are not applicable to Real Estate listings and Half.com. To avoid loss of shipping details when revising a listing, you must include all ShippingDetails fields that were originally provided. GetMyeBayBuying, GetMyeBaySelling: ShippingDetails is not returned (with a request version 677 or higher) if (a) the item is marked as local pickup only with a cost of 0 or (b) ShipToLocation is None. (With a request version lower than 677, ShippingDetails is returned.) See:
|
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate |
CalculatedShippingRateType | Conditional |
Details pertinent to one or more items for which calculated shipping has been offered by the seller, such as package dimension and weight and packaging/handling costs. If your call specifies a large-dimension item listed with UPS, see Dimensional Weight limit on UPS shipping services results in failure of shipping calculator. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .OriginatingPostalCode |
string | Conditional | Postal code for the location from which the package will be shipped. Required for calculated shipping. Use Item.PostalCode to specify the location of the item used for searches by location. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .PackageDepth |
MeasureType (decimal) | Conditional |
Depth of the package, in whole number of inches, needed to ship the item. This is validated against the selected shipping service. Upon mismatch, a message is returned, such as, "Package dimensions exceeds maximum allowable limit for service XXXXX," where XXXXX is the name of the shipping service. For calculated shipping only. Only returned if the seller specified the value for the item. (In many cases, the seller only specifies the weight fields.) Developer impact: UPS requires dimensions for any Ground packages that are 3 cubic feet or larger and for all air packages, if they are to provide correct shipping cost. If package dimensions are not included for an item listed with calculated shipping, the shipping cost returned will be an estimate based on standard dimensions for the defined package type. eBay enforces a dimensions requirement on listings so that buyers receive accurate calculated shipping costs. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .PackageLength |
MeasureType (decimal) | Conditional | Length of the package, in whole number of inches, needed to ship the item. Upon mismatch, a message is returned, such as, "Package dimensions exceeds maximum allowable limit for service XXXXX," where XXXXX is the name of the shipping service. For calculated shipping only. Only returned if the seller specified the value for the item. (In many cases, the seller only specifies the weight fields.) |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .PackageWidth |
MeasureType (decimal) | Conditional | Width of the package, in whole number of inches, needed to ship the item. Upon mismatch, a message is returned, such as, "Package dimensions exceeds maximum allowable limit for service XXXXX," where XXXXX is the name of the shipping service. For calculated shipping only. Only returned if the seller specified the value for the item. (In many cases, the seller only specifies the weight fields.) |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .PackagingHandlingCosts |
AmountType (double) | Optional | Fees a seller might assess for the shipping of the item (in addition to whatever the shipping service might charge). Any packaging/handling cost specified on input is added to each shipping service on output. If domestic and international calculated shipping is offered for an item and if packaging/handling cost is specified only for domestic shipping, that cost will be applied by eBay as the international packaging/handling cost. (To specify a international packaging/handling cost, you must always specify a domestic packaging/handling cost, even if it is 0.) When UPS is one of the shipping services offered by the seller, package dimensions are required on list/relist/revise. For calculated shipping only. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .ShippingIrregular |
boolean | Optional | Whether a package is irregular and therefore cannot go through the stamping machine at the shipping service office and thus requires special or fragile handling. For calculated shipping only. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .ShippingPackage |
ShippingPackageCodeType | Conditional |
The nature of the package used to ship the item(s). Required for calculated shipping only.
Applicable values: See ShippingPackage. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .WeightMajor |
MeasureType (decimal) | Conditional |
WeightMajor and WeightMinor are used to specify the weight of a shipping package. Here is how you would represent a package weight of 5 lbs 2 oz: <WeightMajor unit="lbs">5</WeightMajor> <WeightMinor unit="oz">2</WeightMinor> See http://www.ups.com for the maximum weight allowed by UPS. Above this maximum, the shipping type becomes Freight, an option that can only be selected via the eBay Web site and not via API. The weight details are validated against the selected shipping service. For calculated shipping or for flat rate shipping if shipping rate tables are specified and the shipping rate table uses weight surcharges. Required on input when calculated shipping is used. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .CalculatedShippingRate .WeightMinor |
MeasureType (decimal) | Conditional |
See the definition of WeightMajor. For calculated shipping or for flat rate shipping if shipping rate tables are specified and the shipping rate table uses weight surcharges. (When used with the shipping rate tables with weight surcharge, any WeightMinor value greater than zero results in WeightMajor getting rounded up in the shipping cost calculation for example, 1 lb, 2 oz is rounded up to 2 lbs.) Required on input when calculated shipping is used. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .ExcludeShipToLocation |
string | Conditional,
repeatable: [0..*] |
Use this field to specify an international country or region, or a special domestic location, such as 'PO Box' (in US) or 'Packstation' (in DE), to where you will not ship the associated item. Repeat this element in the call request for each location that you want to exclude as a shipping destination for your item. Set ShipToRegistrationCountry to true to have your ExcludeShipToLocation settings applied to your listing. The locations you have excluded display in the Shipping and Handling section of your item listing. If a buyer's primary ship-to location is a location that you have listed as an excluded ship-to location (or if the buyer does not have a primary ship-to location), they will receive an error message if they attempt to buy or place a bid on your item. The exclude ship-to location values are eBay regions and countries. To see the valid exclude ship-to locations for a specified site, call GeteBayDetails with DetailName set to ExcludeShippingLocationDetails. Repeat GeteBayDetails for each site on which you list. This field works in conjunction with Item.ShipToLocations to create a set of international countries and regions to where you will, and will not, ship. You can list a region in the ShipToLocations field, then exclude specific countries within that region with this field (for example, you can specify Africa in ShipToLocations, yet exclude Chad with a ExcludeShipToLocation setting). In addition, if your ShipToLocations is Worldwide, you can use this field to specify both regions and countries that you want to exclude from your shipping destinations. You can specify a default set of locations to where you will not ship in My eBay. If you create an Exclude Ship-To List, it is, by default, in effect when you list items. However, if you specify any value in this field on input, it nullifies the default settings in your Exclude Ship-To List. (If you use ExcludeShipToLocation when you list an item, you will need to list all the locations to where you will not ship the associated item, regardless of the default settings in your Exclude Ship-To List.) Specify NONE in this field to override the default Exclude Ship-To List you might have set up in My eBay and indicate that you do not want to exclude any shipping locations from the respective item listing. Note: To enable your default Exclude Ship-To List, you must enable Exclude Shipping Locations and Buyer Requirements in your My eBay Site Preferences. For details, see the KnowledgeBase Article HowTo: ExcludeShipToLocation. Applicable values: See CountryCodeType, ShippingRegionCodeType |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .InsuranceFee |
AmountType (double) | Optional |
Cost of shipping insurance set by the seller. If the buyer bought more than one of this item, this is the insurance for just a single item. Exception: for GetItemShipping, this is proportional to QuantitySold. Value should be greater than 0.00 if InsuranceOption is Optional or Required. For flat shipping only. Optional as input and only allowed if ChangePaymentInstructions is true. This field is ignored when InsuranceOption is not specified in the request. Valid only on the following sites: FR and IT Applicable to Half.com for GetOrders. Default: 0.00. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .InsuranceOption |
InsuranceOptionCodeType | Optional |
Whether the seller offers shipping insurance and, if so, whether the insurance is optional or required. Optional as input and only allowed if ChangePaymentInstructions is true. If this field is not included in the request, values specified in the InsuranceFee field will be ignored. Note: Note that sellers are responsible for the items they sell until they safely arrive in their customers' hands, and that offering buyer-paid insurance (either as an optional or required service) infers that the buyer is somehow responsible for the safe delivery of the items they purchase. This notion can reduce buyer confidence in the marketplace and the practice of including buyer- paid shipping insurance in your item listings is discouraged. This field is always returned with a request version lower than 635. With a request version of 635 or higher, this field is only returned if the value is other than NotOffered. Valid only on the following sites: FR and IT If you include buyer-paid shipping insurance for an item listed on one of the sites that supports this option, a buyer on a site that does not support buyer-paid shipping insurance can still purchase the item. In these cases, the buyer is responsible for all the shipping insurance terms that have been outlined in the item listing. Applicable to Half.com Applicable values: • CustomCode (in/out) Reserved for internal or future use • IncludedInShippingHandling (in/out) The seller is not charging separately for shipping insurance costs; any insurance is already included in the base shipping cost. • NotOffered (in/out) The seller does not offer shipping insurance to the buyer. • Optional (in/out) The seller offers the buyer the choice of paying for shipping insurance or not. • Required (in/out) The seller requires that the buyer pay for shipping insurance. (Not all values in InsuranceOptionCodeType apply to this field.) |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .InternationalShippingServiceOption |
InternationalShippingServiceOptionsType | Optional,
repeatable: [0..*] |
Shipping costs and options related to an international shipping service. If used, at least one domestic shipping service must also be provided in ShippingServiceOptions. If you specify multiple InternationalShippingServiceOption nodes, the repeating nodes must be contiguous. That is, you cannot insert other nodes between InternationalShippingServiceOption nodes. If you specify ShippingDetails when you revise or relist an item but you omit InternationalShippingServiceOption, eBay will drop the international shipping services from the listing. This may also have unintended side effects, as other fields that depend on this data may be dropped as well. To retain the shipping services and dependent fields when you modify other shipping details, it may be simplest to specify all ShippingDetails that you still want to include in the listing. A seller can offer up to four domestic shipping services and up to five international shipping services. All specified domestic and international shipping services must be the same shipping type (for example, Flat versus Calculated). Note: As of June 2011, the number of domestic and international shipping services that a seller may offer the buyer has increased. The number of domestic shipping services that may be offered has increased from 3 to 4, and the number of international shipping service options has increased from 3 to 5. For GetItemShipping, results are filtered: if any service is not available in the buyer's region, it is removed. If no services remain after this filtering, a warning is returned. Not applicable to Half.com or eBay Motors vehicle listings. See Overview of the API Schema for rules regarding repeating instances of a nodes (nodes for which maxOccurs is "unbounded" or is greater than 1). |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .InternationalShippingServiceOption .ShippingService |
token | Conditional |
An international shipping service being offered by the seller to ship an item to a buyer. For a list of valid values, call GeteBayDetails with DetailName set to ShippingServiceDetails. The ShippingServiceDetails.ValidForSellingFlow flag must also be present. Otherwise, that particular shipping service option is no longer valid and cannot be offered to buyers through a listing. For flat and calculated shipping. See GeteBayDetails. Applicable values: See ShippingServiceCodeType |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .InternationalShippingServiceOption .ShippingServiceAdditionalCost |
AmountType (double) | Conditional | The cost of shipping each additional item beyond the first item. For input, this is required if the listing is for multiple items. For single-item listings, it should be zero (or is defaulted to zero if not provided). For flat shipping only. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .InternationalShippingServiceOption .ShippingServiceCost |
AmountType (double) | Conditional |
The meaning of this element depends on the call and on whether flat or calculated shipping has been selected. (For example, it could be the cost to ship a single item, the cost to ship all items, or the cost to ship just the first of many items, with ShippingServiceAdditionalCost accounting for the rest.) When returned by GetItemShipping, it includes the packaging and handling cost. For flat and calculated shipping. If a shipping service has been specified, GetItem returns the shipping service cost, even if the cost is zero. Otherwise, cost is not returned. See Shipping. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .InternationalShippingServiceOption .ShippingServicePriority |
int | Conditional |
This integer value controls the order (relative to other shipping services) in which the corresponding ShippingService will appear in the View Item and Checkout page. Sellers can specify up to five international shipping services (with five InternationalShippingServiceOption containers), so valid values are 1, 2, 3, 4, and 5. A shipping service with a ShippingServicePriority value of 1 appears at the top. Conversely, a shipping service with a ShippingServicePriority value of 5 appears at the bottom of a list of five shipping service options. This field is applicable to Flat and Calculated shipping. This field is not applicable to Half.com listings. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .InternationalShippingServiceOption .ShipToLocation |
string | Conditional,
repeatable: [0..*] |
An international location or region to where the item seller will ship the item. Use GeteBayDetails to determine which locations are valid per site. These values are string equivalents of values found in ShippingRegionCodeType and CountryCodeType. For the AddItem family of calls, this field is required if any international shipping service is specified.
See ShipToLocation. Applicable values: See CountryCodeType, ShippingRegionCodeType |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .PaymentInstructions |
string | Optional |
Payment instructions (or message) from the seller to the buyer. These instructions appear on eBay's View Item page and on eBay's checkout page when the buyer pays for the item. Sellers usually use this field to specify payment instructions, how soon the item will shipped, feedback instructions, and other reminders that the buyer should be aware of when they bid on or buy an item. This field can be specified regardless of the shipping type eBay only allows 500 characters as input, but due to the way the eBay Web site UI treats characters, this field can return more than 500 characters in the response. Characters like & and ' (apostrophe/single quote) count as 5 characters each. Use DeletedField to remove this value when revising or relisting an item. Applicable to eBay Motors (usually used to elaborate on the return policy). Not applicable to Half.com. Max length: 1000. See:
|
|
GetRecommendationsRequestContainer .Item.ShippingDetails.SalesTax |
SalesTaxType | Optional |
Sales tax details. US (site 0) and Motors (site 100) sites only, excluding vehicle listings. Flat and calculated shipping. Applicable to Half.com (for GetOrders). |
|
GetRecommendationsRequestContainer .Item.ShippingDetails.SalesTax .SalesTaxPercent |
float | Optional |
Percent of an item's price to be charged as the sales tax for the order. The value passed in is stored with a precision of 3 digits after the decimal point (##.###). Applicable to Half.com (for GetOrders). |
|
GetRecommendationsRequestContainer .Item.ShippingDetails.SalesTax .SalesTaxState |
string | Optional |
State or jurisdiction for which the sales tax is being collected. Only returned if the seller specified a value. Applicable to Half.com (for GetOrders). |
|
GetRecommendationsRequestContainer .Item.ShippingDetails.SalesTax .ShippingIncludedInTax |
boolean | Optional |
(US only) Whether shipping costs were part of the base amount that was taxed. Flat or calculated shipping. Applicable to Half.com (for GetOrders). |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .ShippingServiceOptions |
ShippingServiceOptionsType | Conditional,
repeatable: [0..*] |
Shipping costs and options related to domestic shipping services offered by the seller. Flat and calculated shipping. Required if InternationalShippingServiceOption is specified. For flat shipping, a maximum shipping cost may apply when listing. See Shipping documentation for details about Maximum Flat Rate Shipping Costs. If you specify multiple ShippingServiceOptions nodes, the repeating nodes must be contiguous. For example, you can insert InternationalShippingServiceOption nodes after a list of repeating ShippingServiceOptions nodes, but not between them: <ShippingServiceOptions>...</ShippingServiceOptions> <ShippingServiceOptions>...</ShippingServiceOptions> <ShippingServiceOptions>...</ShippingServiceOptions> <InternationalShippingServiceOption>...</InternationalShippingServiceOption> <InternationalShippingServiceOption>...</InternationalShippingServiceOption> If you specify ShippingDetails when you revise or relist an item but you omit ShippingServiceOptions, eBay will drop the domestic shipping services from the listing. This may also have unintended side effects, as other fields that depend on this data may be dropped as well. To retain the shipping services and dependent fields when you modify other shipping details, it may be simplest to specify all ShippingDetails that you still want to include in the listing. A seller can offer up to four domestic shipping services and up to five international shipping services. All specified domestic and international shipping services must be the same shipping type (for example, Flat versus Calculated). Note: As of June 2011, the number of domestic and international shipping services that a seller may offer the buyer has increased. The number of domestic shipping services that may be offered has increased from 3 to 4, and the number of international shipping service options has increased from 3 to 5. For GetItemShipping, results are filtered: if any service is not available in the buyer's region, it is removed. If no services remain after this filtering, a warning is returned. Not applicable to Half.com or eBay Motors vehicle listings. See Overview of the API Schema for rules regarding repeating instances of a nodes (nodes for which maxOccurs is "unbounded" or is greater than 1). |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .ShippingServiceOptions .ShippingService |
token | Conditional |
A shipping service option being offered by the seller to ship an item to a buyer. For a list of valid ShippingService values, call GeteBayDetails with DetailName set to ShippingServiceDetails. The ShippingServiceDetails.ValidForSellingFlow flag must also be present. Otherwise, that particular shipping service option is no longer valid and cannot be offered to buyers through a listing. For flat and calculated shipping. Also applicable to Half.com (for GetOrders). If there are two or more services and one is "pickup", "pickup" must not be specified as the first service. See GeteBayDetails. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .ShippingServiceOptions .ShippingServiceAdditionalCost |
AmountType (double) | Conditional | The cost of shipping each additional item beyond the first item. For input, this is required if the listing is for multiple items. For single-item listings, it should be zero (or is defaulted to zero if not provided). For flat shipping only. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .ShippingServiceOptions .ShippingServiceCost |
AmountType (double) | Conditional |
The meaning of this element depends on the call and on whether flat or calculated shipping has been selected. (For example, it could be the cost to ship a single item, the cost to ship all items, or the cost to ship just the first of many items, with ShippingServiceAdditionalCost accounting for the rest.) When returned by GetItemShipping, it includes the packaging and handling cost. For flat and calculated shipping. If a shipping service has been specified (even LocalPickup), GetItem returns the shipping service cost, even if the cost is zero. Otherwise, cost is not returned. If this is for calculated shipping for a listing that has not yet ended, note that the cost cannot be determined until the listing has ended and the buyer has specified a postal code. For GetItemShipping, promotional shipping savings is reflected in the cost, if applicable. If the promotional shipping option is lower than other shipping services being offered, the savings is reflected in the returned shipping cost. The shipping service named Promotional Shipping Service (or whatever is the localized name for it) is included among the shipping services. If the promotional shipping cost is lower than the cost of other shipping services being offered, it is presented first in the list. (The LOWEST shipping service cost is always presented first, regardless of whether there is promotional shipping.) Also applicable to Half.com (for GetOrders). |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .ShippingServiceOptions .ShippingServicePriority |
int | Conditional |
This integer value controls the order (relative to other shipping services) in which the corresponding ShippingService will appear in the View Item and Checkout page. Sellers can specify up to four domestic shipping services (with four ShippingServiceOptions containers), so valid values are 1, 2, 3, and 4. A shipping service with a ShippingServicePriority value of 1 appears at the top. Conversely, a shipping service with a ShippingServicePriority value of 4 appears at the bottom of a list of four shipping service options. This field is applicable to Flat and Calculated shipping. This field is not applicable to Half.com listings. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .ShippingServiceOptions .ShippingSurcharge |
AmountType (double) | Conditional | An additional fee to charge US buyers who have the item shipped via UPS or FedEx to Alaska, Hawaii or Puerto Rico. Can only be assigned a value for the eBay US site and for items in the Parts and Accessories category of the eBay Motors site. Only returned if set. If some line items in an order have a surcharge, surcharge is added only for those line items. Flat rate shipping only. |
|
GetRecommendationsRequestContainer .Item.ShippingDetails .ShippingType |
ShippingTypeCodeType | Optional |
The shipping cost model offered by the seller. This is not returned for various calls since shipping type can be deduced: if a CalculatedShippingRate structure is returned by the call, the shipping type is Calculated. Otherwise, it is one of the other non-Calculated shipping types. GetItemShipping and GetItemTransactions: If the type was a mix of flat and calculated services, this is set simply to Flat or Calculated because it is the buyer's selection that results in one of these. Not applicable to Half.com. Applicable values: • Calculated (in/out) Calculated shipping model: the cost of shipping is determined in large part by the seller-offered and buyer-selected shipping service. The seller might assess an additional fee via PackagingHandlingCosts. • CalculatedDomesticFlatInternational (in/out) The seller specified one or more calculated domestic shipping services and one or more flat international shipping services. • CustomCode (in/out) Reserved for future use. • Flat (in/out) Flat shipping model: the seller establishes the cost of shipping and cost of shipping insurance, regardless of what any buyer-selected shipping service might charge the seller. • FlatDomesticCalculatedInternational (in/out) The seller specified one or more flat domestic shipping services and one or more calculated international shipping services. • FreightFlat (in/out) Freight shipping model: freight shipping may be used when flat or calculated shipping cannot be used due to the greater weight of the item. See "Specifying Freight Shipping" in the Shipping chapter for details on freight shipping. • NotSpecified (in/out) The seller did not specify the shipping type. (Not all values in ShippingTypeCodeType apply to this field.) |
|
GetRecommendationsRequestContainer .Item .ShippingTermsInDescription |
boolean | Optional |
Indicates whether details about shipping costs and arrangements are specified in the item description. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.ShipToLocations |
string | Optional,
repeatable: [0..*] |
An international location or region to which the seller is willing to ship, regardless of shipping service. The country of the listing site is added by eBay. Use GeteBayDetails with a DetailName of ShippingLocationDetails to determine which international locations are valid for the site. Omit ShipToLocations if you want to ship only within the country of the listing site. To state that you do not wish to ship at all, set ShipToLocations to None. ReviseItem can add a ShipToLocations. On output, ShipToLocations is the collection of all input item-level ShipToLocations plus international shipping service-level ShipToLocation values. If you have specified a region to which you will ship (such as Asia), you can use ExcludeShipToLocation to exclude certain countries within that region to where you will not ship (such as Afghanistan). Not applicable to Half.com. Max length: length of longest name in ShippingRegionCodeType and CountryCodeType. See:
Applicable values: See CountryCodeType, ShippingRegionCodeType |
|
GetRecommendationsRequestContainer .Item.Site |
SiteCodeType | Required |
The name of the site on which the item is listed. The listing site affects the business logic and validation rules that are applied to the request, which in turn affect the values that are returned in the response, as well as values that appear on the eBay Web site. For example, the listing site can affect the validation of Category in listing requests, international business seller requirements, the values of converted (localized) prices in responses, the item-related time stamps that are displayed on the eBay Web site, the visibility of the item in some types of searches, and other information. In some cases, the rules are determined by a combination of the site, the user's registration address, and other information. You cannot change the site when you revise a listing. When you specify Item.Site in AddItem or AddFixedPriceItem, it must be consistent with the numeric site ID that you specify in the request URL (for the SOAP API) or the X-EBAY- API-SITEID header (for the XML API). Not applicable to Half.com. Applicable values: See Site. See:
|
|
GetRecommendationsRequestContainer .Item.SKU |
SKUType (string) | Optional |
A SKU (stock keeping unit) is an identifier defined by a seller. Some sellers use SKUs to track complex flows of products and information on the client side. A seller can specify a SKU when listing an item with AddItem and related calls. eBay preserves the SKU on the item, enabling you to obtain it before and after an order line item is created. (SKU is recommended as an alternative to ApplicationData.) A SKU is not required to be unique, when you track listings by their ItemID (the default tracking method). A seller can specify a particular SKU on one item or on multiple items. Different sellers can use the same SKUs. If you want to use SKU instead of ItemID as a unique identifier (such as when retrieving items and orders), you can set Item.InventoryTrackingMethod to SKU in AddFixedPriceItem and related calls. In this case, the SKU must be unique across your (the seller's) active listings. Note that if you relist the item, you must reset Item.InventoryTrackingMethod to SKU; otherwise the relisted item will default to ItemID as the tracking method. If both ItemID and SKU are specified in item-retrieval and order-retrieval calls that support the use of SKU as a unique identifier, the ItemID value takes precedence and is used to identify the listing. For multi-variation listings, the SKU can be used to uniquely identify a variation that is being revised or relisted. If InventoryTrackingMethod is ItemID, an ItemID is also required. When both SKU and VariationSpecifics are passed in the request, the variation specifics take precedence as the unique identifier. Note: The eBay Web site UI cannot identify listings by SKU. For example, My eBay pages and Search pages all identify listings by item ID. When a buyer contacts you via eBay's messaging functionality, eBay uses the item ID as the identifier. Buyer-focused APIs (like the Shopping API) also do not support SKU as an identifier. For revising and relisting only: To remove a SKU when you revise or relist an item, use DeletedField. (You cannot remove a SKU when Item.InventoryTrackingMethod is set to SKU.) For GetMyeBaySelling, this is only returned if set. Not applicable to Half.com. Max length: 50. See eBay Merchant Data API for AddFixedPriceItem and ReviseFixedPriceItem. |
|
GetRecommendationsRequestContainer .Item.StartPrice |
AmountType (double) | Optional |
Note: In late October 2010, for the US site, users who are registering as eBay sellers for the first time are subject to seller limits which limit the quantity of items and/or the total listing value of the items. This applies to new sellers, not currently to existing sellers. (The GetMyeBaySelling call returns the remaining item quantity and remaining total value under the limits for the seller, if any such limits exist for the seller.) If a call to add an item or revise an item would result in the exceeding of these limits, the add item or revise item call will fail. For auctions, the value limits apply to the start price, not the final sale amount. For more information, see the link to Seller Limits below. The original price of the item at listing or re-listing time. If this value changes when the item is revised, the new value becomes the original price. For auction listings: Competitive bidding starts at this value. Once at least one bid has been placed, StartPrice remains the same but CurrentPrice is incremented to the amount of each succeeding bid. If ReservePrice is also specified, the value of StartPrice must be lower than the value of ReservePrice. For input on fixed-price listings (FixedPriceItem) and Store Inventory listings: This is the constant price at which a buyer may purchase the item. GetMyeBaySelling does not return Item.StartPrice for fixed price items--it returns Item.SellingStatus.CurrentPrice. For AddFixedPriceItem and VerifyAddFixedPriceItem: Required when no variations are specified. If variations are specified, use Variation.StartPrice for each variation instead. Also applicable to Half.com (valid range 0.75 to 9999.99). You can revise this field for Half.com listings. See Seller Limits. |
|
GetRecommendationsRequestContainer .Item.Storefront |
StorefrontType | Optional |
Contains information related to the item in the context of a seller's eBay Store. Applicable for auction and fixed-price listings listed by eBay Stores sellers. Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.Storefront .StoreCategory2ID |
long | Optional |
Applicable for eBay Store sellers only. Numeric ID for a second custom category that the seller created in their eBay Store. eBay Stores sellers can create up to 300 custom categories for their stores. (One additional Store category cannot be customized and retains the value of "Other"). If you specify an invalid value, the values are the same for both the primary and secondary store categories, or if the seondary store category is specified but the primary is left blank (or other), the system resets the value to 0 (None). In short, the primary store category must be set to something meaningful and different from the second store category in order to set the secondary store category to a value other than 0. In GetProducts, this field currently returns 0. As a workaround, use GetItem or related calls to get the ID. |
|
GetRecommendationsRequestContainer .Item.Storefront .StoreCategoryID |
long | Optional | Numeric ID for a custom category that the seller created in their eBay Store, if any. eBay Stores sellers can create up to three levels of custom categories for their stores. Items can only be listed in store categories that have no child categories (subcategories). If you attempt to list an item in a category that has subcategories, the call response contains a warning, and the item is listed in the Other store category. In GetProducts, this field currently returns 0. As a workaround, use GetItem or related calls to get the ID. |
|
GetRecommendationsRequestContainer .Item.SubTitle |
string | Optional |
Subtitle to use in addition to the title. Provides more keywords when buyers search in titles and descriptions. You cannot use HTML in the Subtitle. (HTML characters will be interpreted literally as plain text.) If you pass any value, this feature is applied (with applicable fees). Not applicable to listings in US eBay Motors passenger vehicle, motorcycle, and "other vehicle" categories or to listings in CA eBay Motors passenger vehicle and motorcycle categories. For eBay Motors categories that do not support this field, use Item Specifics (AttributeSetArray) to specify the vehicle subtitle. When you revise a item, you can add, change, or remove the subtitle. Not applicable to Half.com. Max length: 55. See:
|
|
GetRecommendationsRequestContainer .Item.ThirdPartyCheckout |
boolean | Optional |
As of July 1, 2011, third-party applications can no longer be used for checkout. All purchased items must go through the eBay Checkout flow. This field can no longer be passed into the Add Item family of calls. This field will be returned in some calls (that return the Item container) if it was set to True at listing time (for listings created before July 1, 2011). If this field was set to True at listing time, the user must include this field and set it to False in the Relist and Revise Item family of calls. Otherwise, the caller may get an error. |
|
GetRecommendationsRequestContainer .Item .ThirdPartyCheckoutIntegration |
boolean | Optional |
As of July 1, 2011, third-party applications can no longer be used for checkout. All purchased items must go through the eBay Checkout flow. This field can no longer be passed into the Add Item family of calls. This field will be returned in some calls (that return the Item container) if it was set to True at listing time (for listings created before July 1, 2011). If this field was set to True at listing time, the user must include this field and set it to False in the Relist and Revise Item family of calls. Otherwise, the caller may get an error. Be aware that you may need to use SetNotificationPreferences to change the ApplicationURL value if you were formerly having Checkout notifications sent to your third-party checkout application. |
|
GetRecommendationsRequestContainer .Item.Title |
string | Conditional |
Name of the item as it appears in the listing or search results. Title is required for most items. This field is only optional if you leverage Pre-filled Item Information by using the Item.ProductListingDetails or Item.ExternalProductID containers. You cannot use HTML or JavaScript in the Title. (HTML characters will be interpreted literally as plain text.) For the AddItem family of calls: Not applicable to Half.com. For ReviseItem and ReviseFixedPriceItem You can only add or change the item title if the listing has no bids (for auctions) or sales (for fixed-price listings) and the listing does not end within 12 hours. For GetItemRecommendations: More keywords in the title usually result in more relevant Listing Analyzer recommendations. Note: The maximum length of an eBay Item Title has increased to 80 characters as of September 2011. Max length: 80. |
|
GetRecommendationsRequestContainer .Item.UseTaxTable |
boolean | Optional |
Indicates whether the seller's tax table is to be used when applying and calculating sales tax for an order line item. A sales tax table can be created programmatically using the SetTaxTable call, or it can be created manually in My eBay's Selling Preferences. If UseTaxTable is set to true, the values contained in the seller's sales tax table will supersede the values contained in the Item.ShippingDetails.SalesTax container (if included in the request). Not applicable to Half.com. |
|
GetRecommendationsRequestContainer .Item.VATDetails |
VATDetailsType | Conditional |
Container for eBay's VAT features. A business seller can choose to offer an item exclusively to bidders and buyers that also represent businesses. Only applicable when the item is listed in a B2B-enabled category (on a site that supports B2B business features). Note: The India site (Global ID 203) does not accept VAT values in item listings. If you submit an item to the India site with a VAT value, eBay generates a warning message that indicates the listing was accepted, but the VAT value was removed. To include the VAT, relist the item with a Price value that includes the VAT. Sellers are solely responsible for compliance relating to tax legislation in India. Not applicable to Half.com. See:
|
|
GetRecommendationsRequestContainer .Item.VATDetails .BusinessSeller |
boolean | Conditional | If true, this indicates that the seller is a business user and intends to use listing features that are offered to business users only. Applicable only to business sellers residing in Germany, Austria, or Switzerland who are listing in a B2B VAT- enabled category on the eBay Germany (DE), Austria (AT), or Switzerland (CH) sites. The seller must have a valid VAT ID registered with eBay. This must be set to true if RestrictedToBusiness is true. It has no effect (and it's not returned) if RestrictedToBusiness is false. If an item was not qualified as a business item when originally listed, but meets the conditions for business items when the item is revised or relisted, the seller can convert the item to a business item by specifying the appropriate VAT details. See the eBay Web Services guide for more information and additional rules. |
|
GetRecommendationsRequestContainer .Item.VATDetails .RestrictedToBusiness |
boolean | Optional | If true, this indicates that the seller elects to offer the item exclusively to business users. If false (or not returned), this indicates that the seller elects to offer the item to all users. Applicable only to business sellers residing in Germany, Austria, or Switzerland who are listing in a B2B VAT-enabled category on the eBay Germany (DE), Austria (AT), or Switzerland (CH) sites. If this argument is true, the seller must have a valid VAT-ID registered with eBay, and BusinessSeller must also be true. |
|
GetRecommendationsRequestContainer .Item.VATDetails.VATPercent |
float | Conditional |
VAT rate for the item, if any. When the VATPercent is specified, the item's VAT information appears on the item's listing page. In addition, the seller can choose to print an invoice that includes the item's net price, VAT percent, VAT amount, and total price. Since VAT rates vary depending on the item and on the user's country of residence, a seller is responsible for entering the correct VAT rate; it is not calculated by eBay. To specify a VATPercent, a seller must have a VAT-ID registered with eBay and must be listing the item on a VAT-enabled site. Max applicable length is 6 characters, including the decimal (e.g., 12.345). The scale is 3 decimal places. (If you pass in 12.3456, eBay may round up the value to 12.346.) Note: The View Item page may display the precision to 2 decimal places with no trailing zeros. However, the full value you send in is stored. Min: 0. Max: 30. |
|
GetRecommendationsRequestContainer .Item.VIN |
string | Conditional |
Vehicle Identification Number, which is a unique serial number for a motor vehicle. Applicable to listings in US eBay Motors Cars and Trucks, Motorcycle, and some Powersport, Boats and RV campers categories; and to Cars and Trucks listings in CA, CAFR and AU eBay Motors. For the US, CA, and CAFR eBay Motors sites, required for cars and trucks from model year 1981 and later. (The US developed national standards for VIN values as of 1981.) For the eBay Australia site, required for vehicles from model year 1989 or later. For the eBay Australia site, only appears on the View Item page if you also specify the date of first registration in the listing's item specifics. Appears in the VIN field in the Item Specifics section of eBay's View Item page. Not applicable to Half.com. Until May 2012, you can either specify Item.VIN or you can specify the VIN by using ID-based attributes (in Item.AttributeSetArray). If you specify the VIN attribute, eBay will migrate the value to this Item.VIN field for you. After this conversion happens, GetItem may only return the VIN in Item.VIN, not in Item.AttributeSetArray. If you list eBay Motors vehicles, we recommend that you begin adopting Item.VIN in your application immediately. Max length: 17. |
|
GetRecommendationsRequestContainer .Item.VRM |
string | Optional |
Vehicle Registration Mark, which is a unique identifier for a motor vehicle. Applicable to listings in UK eBay Motors Cars and Trucks, Motorcycle, and some Powersport categories. Appears as a VRM field in the Item Specifics section of eBay's View Item page. On the View Item page, the VRM value is masked (i.e., only a portion of the value is shown to users). In the GetItem response, the VRM is only returned if the call is made by the seller (i.e., the AuthToken is associated with the vehicle's seller). Not applicable to Half.com. Until May 2012, you can either specify Item.VRM or you can specify the VRM by using ID-based attributes (in Item.AttributeSetArray). If you specify the VRM attribute, eBay will migrate the value to this Item.VRM field for you. After this conversion happens, GetItem may only return the VRM in Item.VRM, not in Item.AttributeSetArray. If you list eBay Motors vehicles, we recommend that you begin adopting Item.VRM in your application immediately. Max length: 7. |
|
GetRecommendationsRequestContainer .ListingFlow |
ListingFlowCodeType | Optional |
The listing flow for which the seller is seeking Listing Analyzer recommendations. Not applicable to results from other recommendation engines (i.e., the Suggested Attributes engine or the Product Pricing engine). The default flow is AddItem. Default: AddItem. Applicable values: • AddItem (in) AddItem (Sell Your Item) listing flow. • CustomCode (in) Reserved for internal or future use. • RelistItem (in) RelistItem listing flow. • ReviseItem (in) ReviseItem (Revise Your Item) listing flow. |
|
GetRecommendationsRequestContainer .Query |
string | Conditional |
One or more keywords to search for when using the Suggested Attributes engine. Required when SuggestedAttributes is specified as the recommendation engine (including when no recommendation engines are specified). Only the listing title is searched. The words "and" and "or" are treated like any other word. Blank searches are not allowed (and result in a warning). Max length: 350 (characters). |
|
GetRecommendationsRequestContainer .RecommendationEngine |
RecommendationEngineCodeType | Optional,
repeatable: [0..*] |
A recommendation engine to run. If no engines are specified, all available recommendation engines will run. Some engines require additional fields, such as Item.PrimaryCategory.CategoryID, to be specified. If the ProductPricing engine is specified but Item.ProductListingDetails is not specified, no Product Pricing engine results are returned.
Applicable values: • CustomCode (in) Reserved for internal or future use. • ItemSpecifics (in) Custom Item Specifics engine. Returns the most popular names and values to use for custom Item Specifics based the requested category (and the Title, if specified). • ListingAnalyzer (in) Listing Analyzer engine; Returns tips related to fields that a seller wants to specify in a listing. • ProductPricing (in) Product Pricing engine. Returns average start and sold prices of completed items that were listed a specified product ID. • SIFFTAS (in) Reserved for internal or future use. • SuggestedAttributes (in) Suggested Attributes engine. Returns suggested attributes and catalog products (for Pre-filled Item Information) that have been used by other sellers who listed similar items in the same category. |
| Input Detail Controls Samples Change History Top Errors for GetItemRecommendations User Notes |
The box below lists all fields that might be returned in the response. 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 not returned (or soon will not be returned) or are not operational (or soon will be non-operational).
The XML prototype does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).
<?xml version="1.0" encoding="utf-8"?>
<GetItemRecommendationsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
<!-- Standard Output Fields -->
<Ack> AckCodeType </Ack>
<Build> string </Build>
<CorrelationID> string </CorrelationID>
<Errors> ErrorType
<ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
<ErrorCode> token </ErrorCode>
<ErrorParameters ParamID="string"> ErrorParameterType
<Value> string </Value>
</ErrorParameters>
<!-- ... more ErrorParameters nodes here ... -->
<LongMessage> string </LongMessage>
<SeverityCode> SeverityCodeType </SeverityCode>
<ShortMessage> string </ShortMessage>
</Errors>
<!-- ... more Errors nodes here ... -->
<HardExpirationWarning> string </HardExpirationWarning>
<Timestamp> dateTime </Timestamp>
<Version> string </Version>
<!-- Call-specific Output Fields -->
<GetRecommendationsResponseContainer> GetRecommendationsResponseContainerType
<AttributeRecommendations> AttributeRecommendationsType
<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>
</AttributeRecommendations>
<CorrelationID> string </CorrelationID>
<ListingAnalyzerRecommendations> ListingAnalyzerRecommendationsType
<ListingTipArray> ListingTipArrayType
<ListingTip> ListingTipType
<Field> ListingTipFieldType
<CurrentFieldText> string </CurrentFieldText>
<CurrentFieldValue> string </CurrentFieldValue>
<FieldTip> string </FieldTip>
<ListingTipFieldID> string </ListingTipFieldID>
</Field>
<ListingTipID> string </ListingTipID>
<Message> ListingTipMessageType
<HelpURLPath> string </HelpURLPath>
<ListingTipMessageID> string </ListingTipMessageID>
<LongMessage> string </LongMessage>
<ShortMessage> string </ShortMessage>
</Message>
<Priority> int </Priority>
</ListingTip>
<!-- ... more ListingTip nodes here ... -->
</ListingTipArray>
</ListingAnalyzerRecommendations>
<PricingRecommendations> PricingRecommendationsType
<ProductInfo productInfoID="string"> ProductInfoType
<AverageSoldPrice currencyID="CurrencyCodeType"> AmountType (double) </AverageSoldPrice>
<AverageStartPrice currencyID="CurrencyCodeType"> AmountType (double) </AverageStartPrice>
<ProductState> ProductStateCodeType </ProductState>
<Title> string </Title>
</ProductInfo>
</PricingRecommendations>
<ProductListingDetails> ProductListingDetailsType
<DetailsURL> anyURI </DetailsURL>
<ProductDetailsURL> anyURI </ProductDetailsURL>
<ProductReferenceID> string </ProductReferenceID>
</ProductListingDetails>
<ProductRecommendations> ProductRecommendationsType
<Product productInfoID="string"> ProductInfoType
<ProductState> ProductStateCodeType </ProductState>
<Title> string </Title>
</Product>
<!-- ... more Product nodes here ... -->
</ProductRecommendations>
<Recommendations> RecommendationsType
<CategoryID> string </CategoryID>
<NameRecommendation> NameRecommendationType
<HelpText> string </HelpText>
<HelpURL> anyURI </HelpURL>
<Name> string </Name>
<ValidationRules> RecommendationValidationRulesType
<Confidence> int </Confidence>
<MaxValues> int </MaxValues>
<MinValues> int </MinValues>
<Relationship> NameValueRelationshipType
<ParentName> string </ParentName>
</Relationship>
<!-- ... more Relationship nodes here ... -->
<SelectionMode> SelectionModeCodeType </SelectionMode>
<ValueFormat> ValueFormatCodeType </ValueFormat>
<ValueType> ValueTypeCodeType </ValueType>
<VariationPicture> VariationPictureRuleCodeType </VariationPicture>
<VariationSpecifics> VariationSpecificsRuleCodeType </VariationSpecifics>
</ValidationRules>
<ValueRecommendation> ValueRecommendationType
<ValidationRules> RecommendationValidationRulesType
<Confidence> int </Confidence>
<Relationship> NameValueRelationshipType
<ParentName> string </ParentName>
<ParentValue> string </ParentValue>
</Relationship>
<!-- ... more Relationship nodes here ... -->
</ValidationRules>
<Value> string </Value>
</ValueRecommendation>
<!-- ... more ValueRecommendation nodes here ... -->
</NameRecommendation>
<!-- ... more NameRecommendation nodes here ... -->
</Recommendations>
<Title> string </Title>
</GetRecommendationsResponseContainer>
<!-- ... more GetRecommendationsResponseContainer nodes here ... -->
</GetItemRecommendationsResponse>
| Return Value | Type | Occurrence | Meaning |
|---|
| Standard Output Fields [Jump to call-specific fields] |
| Ack | AckCodeType | Always |
A token representing the application-level acknowledgement code that indicates the response status (e.g., success). The AckCodeType list specifies the possible values for Ack.
Applicable values: • CustomCode (out) Reserved for internal or future use. • Failure (out) Request processing failed • Success (out) Request processing succeeded • Warning (out) Request processing completed with warning information being included in the response message (Not all values in AckCodeType apply to this field.) |
| Build | string | Always | This refers to the specific software build that eBay used when processing the request and generating the response. This includes the version number plus additional information. eBay Developer Support may request the build information when helping you resolve technical issues. |
| CorrelationID | string | Conditionally |
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. |
| Errors | ErrorType | Conditionally,
repeatable: [0..*] |
A list of application-level errors (if any) that occurred when eBay processed the request.
See Error Handling. |
| Errors.ErrorClassification | ErrorClassificationCodeType | Conditionally |
API errors are divided between two classes: system errors and request errors.
Applicable values: • CustomCode (out) Reserved for internal or future use. • RequestError (out) An error has occurred either as a result of a problem in the sending application or because the application's end-user has attempted to submit invalid data (or missing data). In these cases, do not retry the request. The problem must be corrected before the request can be made again. If the problem is due to something in the application (such as a missing required field), the application must be changed. If the problem is a result of end-user data, the application must alert the end-user to the problem and provide the means for the end-user to correct the data. Once the problem in the application or data is resolved, resend the request to eBay with the corrected data. • SystemError (out) Indicates that an error has occurred on the eBay system side, such as a database or server down. An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. |
| Errors.ErrorCode | token | Conditionally | A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. See the "Errors by Number" document. |
| Errors.ErrorParameters | ErrorParameterType | Conditionally,
repeatable: [0..*] |
This optional element carries a list of context-specific error variables that indicate details about the error condition. These are useful when multiple instances of ErrorType are returned. |
| Errors.ErrorParameters [ attribute ParamID ] |
string | Conditionally | The index of the parameter in the list of parameter types returned within the error type. |
| Errors.ErrorParameters.Value | string | Conditionally | The value of the variable (e.g., the attribute set ID) |
| Errors.LongMessage | string | Conditionally | A more detailed description of the condition that raised the error. |
| Errors.SeverityCode | SeverityCodeType | Conditionally |
Indicates whether the error is a severe error (causing the request to fail) or an informational error (a warning) that should be communicated to the user.
Applicable values: • CustomCode (out) Reserved for internal or future use • Error (out) Application-level error • Warning (out) Warning or informational error |
| Errors.ShortMessage | string | Conditionally | A brief description of the condition that raised the error. |
| HardExpirationWarning | string | Conditionally | Expiration date of the user's authentication token. Only returned within the 7-day period prior to a token's expiration. To ensure that user authentication tokens are secure and to help avoid a user's token being compromised, tokens have a limited life span. A token is only valid for a period of time (set by eBay). After this amount of time has passed, the token expires and must be replaced with a new token. |
| Timestamp | dateTime | Always |
This value represents the date and time when eBay processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See Time Values in the eBay Web Services guide for information about this time format and converting to and from the GMT time zone. 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, this time value reflects the time the cached response was created. Thus, this value is not necessarily when the request was processed. 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, this time value does reflect when the request was processed. |
| Version | string | Always | The version of the response payload schema. Indicates the version of the schema that eBay used to process the request. See "Standard Data for All Calls" in the eBay Web Services Guide for information on using the response version when troubleshooting "CustomCode" values that appear in the response. |
| Call-specific Output Fields |
| GetRecommendationsResponseContainer | GetRecommendationsResponseContainerType | Always,
repeatable: [1..*] |
Specifies recommended changes or opportunities for improving the data of a single item. If multiple items were processed, a separate GetRecommendationsResponseContainer is returned for each item. Each container includes a user-defined correlation ID to help you match items in the request to recommendations in the response. |
|
GetRecommendationsResponseContainer .AttributeRecommendations |
AttributeRecommendationsType | Conditionally | Contains attribute suggestions returned from the Suggested Attributes engine, if this engine was specified in the request. The results include suggested attributes and values based on the primary category and a string you specify in the Query field. Suggestions may only be returned when the Suggested Attributes engine is specified alone. If you request recommendations by using multiple engines, suggested attribute data might not be returned. If attributes are returned with multiple values, the values are returned in order of rank (i.e., the value that best meets eBay's recommendation criteria is returned first). |
|
GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray |
AttributeSetArrayType | Conditionally | A list of attribute sets containing recommended attributes and values. Returned from GetItemRecommendations when the Suggested Attributes engine is used See the eBay Web Services guide for additional details. |
|
GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray .AttributeSet |
AttributeSetType | Conditionally,
repeatable: [0..*] |
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. |
| GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray .AttributeSet [ attribute attributeSetID ] |
int | Conditionally | 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. Not applicable to Half.com. |
| GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray .AttributeSet [ attribute attributeSetVersion ] |
string | Conditionally |
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. |
|
GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray .AttributeSet.Attribute |
AttributeType | Conditionally,
repeatable: [0..*] |
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 attribute 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. Not applicable to Half.com. |
| GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray .AttributeSet.Attribute [ attribute attributeID ] |
int | Conditionally | 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. |
|
GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray .AttributeSet.Attribute.Value |
ValType | Conditionally,
repeatable: [0..*] |
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. |
|
GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray .AttributeSet.Attribute.Value .ValueID |
int | Conditionally |
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. |
|
GetRecommendationsResponseContainer .AttributeRecommendations .AttributeSetArray .AttributeSet.Attribute.Value .ValueLiteral |
string | Conditionally |
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 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. |
|
GetRecommendationsResponseContainer .CorrelationID |
string | Conditionally | Unique key to distinguish between recommendations for each item. Matches a correlation ID you defined in the request, if any. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations |
ListingAnalyzerRecommendationsType | Conditionally | Contains tips returned from the Listing Analyzer recommendation engine, if this engine was specified in the request (or if no engine was specified). |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray |
ListingTipArrayType | Conditionally | A collection of tips returned from the Listing Analyzer recommendation engine. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip |
ListingTipType | Conditionally,
repeatable: [0..*] |
An individual tip on improving a listing's details. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Field |
ListingTipFieldType | Conditionally | The item field that is associated with the tip. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Field.CurrentFieldText |
string | Conditionally |
A label used to preface the current value of a field. For example, "Current value" would be the CurrentValueText in "Current value: 25". If no label exists, this element is not returned. Max length: 50. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Field.CurrentFieldValue |
string | Conditionally | Current value of the field (in the listing or in the candidate item) or meta-data about the value. For example, if the tip is recommending a longer item title, the CurrentFieldValue might specify the current length of the title. If no current value is available, this information is not returned. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Field.FieldTip |
string | Conditionally |
Related text that appears near a field or at the top of the section within which the field appears in the selling flow. Max length: 125. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Field.ListingTipFieldID |
string | Conditionally | Identifier associated with the item field. Primarily for internal use. This value may change over time. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .ListingTipID |
string | Conditionally | Identifier for the tip. Primarily for internal use. This value may change over time. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Message |
ListingTipMessageType | Conditionally | The tip's message content. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Message.HelpURLPath |
string | Conditionally |
Path part of a URL for a "Learn More" link that points to a relevant eBay Web site online help page. The path is relative to http://pages.ebay.XX, where XX is the 2-letter site code (e.g., http://pages.ebay.de for the eBay Germany site). Applications should append the URL to the appropriate path for the user's site. Max length: 125. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Message.ListingTipMessageID |
string | Conditionally | Identifier for the tip message. Primarily for internal use. This value may change over time. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Message.LongMessage |
string | Conditionally |
Detailed version of the tip message. Max length: 125. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Message.ShortMessage |
string | Conditionally |
Brief version of the tip message. Max length: 125. |
|
GetRecommendationsResponseContainer .ListingAnalyzerRecommendations .ListingTipArray.ListingTip .Priority |
int | Conditionally | The rank of the tip. All tips are ranked by importance. Ranking varies for each site. The rank is always greater than 0. |
|
GetRecommendationsResponseContainer .PricingRecommendations |
PricingRecommendationsType | Conditionally | Contains pricing data returned from the Product Pricing engine, if this engine was specified in the request (or if no engine was specified). |
|
GetRecommendationsResponseContainer .PricingRecommendations .ProductInfo |
ProductInfoType | Conditionally | A product's pricing data (if any) and brief information about the product. |
| GetRecommendationsResponseContainer .PricingRecommendations .ProductInfo [ attribute productInfoID ] |
string | Conditionally | Unique identifier for the product. See the Developer's Guide for information about eBay product IDs. If the primary and secondary category are both catalog-enabled, this ID corresponds to the primary category. |
|
GetRecommendationsResponseContainer .PricingRecommendations .ProductInfo.AverageSoldPrice |
AmountType (double) | Conditionally | The average sold price (winning bid, Buy It Now price, or fixed price), if any, of completed items that were listed with Pre-filled Item Information from this product. |
| GetRecommendationsResponseContainer .PricingRecommendations .ProductInfo.AverageSoldPrice [ attribute currencyID ] |
CurrencyCodeType | Conditionally |
Currency in which the monetary amount is specified. In the AddItem family of calls, the currency can be specified in the Item.Currency field in requests instead. If you do specify this attribute in the AddItem family of calls, the value must match the site currency (i.e., it must be the same as the value in Item.Currency) unless otherwise stated. In the AddItem family of calls, listing fees are returned in the currency of the user's registration site. For example, a user who is registered on the eBay US site always sees their fees returned in USD, even when their listing request is sent to another site, such as eBay UK or eBay Germany. For a list of possible enumeration values, see CurrencyCodeType. |
|
GetRecommendationsResponseContainer .PricingRecommendations .ProductInfo.AverageStartPrice |
AmountType (double) | Conditionally | The average start price (minimum bid), if any, of completed auction items that were listed with Pre-filled Item Information from this product. |
| GetRecommendationsResponseContainer .PricingRecommendations .ProductInfo.AverageStartPrice [ attribute currencyID ] |
CurrencyCodeType | Conditionally |
Currency in which the monetary amount is specified. In the AddItem family of calls, the currency can be specified in the Item.Currency field in requests instead. If you do specify this attribute in the AddItem family of calls, the value must match the site currency (i.e., it must be the same as the value in Item.Currency) unless otherwise stated. In the AddItem family of calls, listing fees are returned in the currency of the user's registration site. For example, a user who is registered on the eBay US site always sees their fees returned in USD, even when their listing request is sent to another site, such as eBay UK or eBay Germany. For a list of possible enumeration values, see CurrencyCodeType. |
|
GetRecommendationsResponseContainer .PricingRecommendations .ProductInfo.ProductState |
ProductStateCodeType | Conditionally |
Indicates that the product has changed or will soon change (usually due to a migration from one catalog to another catalog). Typically, this field is returned for up to 90 days for a given product. After that, the product either no longer returns this field or the product is no longer returned (depending on the state change). This data is primarily applicable to catalogs used by the US, Germany, Austria, and Switzerland sites. Other sites may undergo catalog changes in the future. Applicable values: • CustomCode (out) Reserved for internal or future use. • Delete (out) This product is marked for deletion, and it will not be mapped to another product. You cannot add or relist items that use products marked for deletion. If your application currently uses the product for listing or searching, we recommend that you update your application to use a product that is not scheduled to be merged or deleted. • Merge (out) Some information in this product is scheduled to be merged into another product in the catalog that eBay (or Half.com) is currently using. This product may be removed from the system at any time. If your application currently uses the product for listing or searching, we recommend that you update your application to use a product that is not scheduled to be merged or deleted. • Update (out) This product's details have been updated. If your application currently uses the product for listing or searching, we recommend that you check to make sure the product data still meets your needs. • UpdateMajor (out) This product has changed. This product has been mapped to a newer product in the catalog that eBay (or Half.com) is currently using, and its details have been updated based on the new catalog data. The product reference ID remains the same (but the longer product ID string may have changed). If your application currently uses the product for listing or searching, we recommend that you check to make sure the product data still meets your needs. • UpdateNoDetails (out) This product was previously available in an earlier catalog, but it has not been mapped to a product in the catalog that eBay is currently using. It can still be used to pre-fill listings, but it may contain fewer details than other products. If your application currently uses the product for listing or searching, we recommend that you check to make sure the product data still meets your needs. Not applicable to Half.com. |
|
GetRecommendationsResponseContainer .PricingRecommendations .ProductInfo.Title |
string | Conditionally |
Title associated with the product. This value can be used as the basis for a suggested listing title. If the title is longer than 80 characters, your application should make sure the suggested title has a maximum length of 80 characters so that it will be valid for the AddItem family of calls. Note: The maximum length of an eBay Item Title has increased to 80 characters as of September 2011. Max length: 1024. |
|
GetRecommendationsResponseContainer .ProductListingDetails |
ProductListingDetailsType | Conditionally | Returns catalog product details. This information can be displayed to the seller prior to listing an item with a catalog product. Only returned when the request includes a valid eBay ProductID or ProductReferenceID (in Item.ProductListingDetails). |
|
GetRecommendationsResponseContainer .ProductListingDetails .DetailsURL |
anyURI | Conditionally |
Fully qualified URL for eBay's product details page, which contains optional information about the product (such as a movie's description or film credits). This information is hosted through the eBay Web site and it cannot be edited. Portions of the content are protected by copyright. Applications can include this URL as a link so that end users can view additional descriptive details about the product. |
|
GetRecommendationsResponseContainer .ProductListingDetails .ProductDetailsURL |
anyURI | Conditionally | Fully qualified URL for eBay's product details page, which contains optional information about the product (such as a movie's description or film credits). This information is hosted through the eBay Web site and it cannot be edited. Portions of the content are protected by copyright. Applications can include this URL as a link so that end users can view additional descriptive details about the product. |
|
GetRecommendationsResponseContainer .ProductListingDetails .ProductReferenceID |
string | Conditionally |
eBay's short global reference ID for a catalog product. On the eBay Web site, this is known as the "ePID" or "Product ID". This type of product ID is a fixed reference to a product (regardless of version). Multiple (versioned) ProductID values can be associated with a single product reference ID. You can find product reference IDs for products by using GetProducts (or FindProducts in the Shopping API). You can also find the product ID on eBay's Web site (a numeric value prefixed with "EPID"). You can pass the value with or without the "EPID" prefix; for example "EPID228742" or "228742" (without quotes). If the primary and secondary categories are both catalog-enabled, this ID should correspond to the primary category (not the secondary category). Some sites (such as eBay US, Germany, Austria, and Switzerland) are updating, replacing, deleting, or merging some products (as a result of migrating from one catalog data provider to another). If you specify one of these products in a request, the call may return the product with a warning, or it may return an error if the product has been deleted. Max length: 38 (42 with "EPID"). |
|
GetRecommendationsResponseContainer .ProductRecommendations |
ProductRecommendationsType | Conditionally | Contains zero or more product titles and IDs returned from the Suggested Attributes engine, if this engine was specified in the request (or if no engine was specified). If applicable, use one of the suggested product IDs to list the item with Pre-filled Item Information. |
|
GetRecommendationsResponseContainer .ProductRecommendations .Product |
ProductInfoType | Conditionally,
repeatable: [0..*] |
A suggested product to use to list an item with Pre-filled Item Information. Returned from GetItemRecommendations when the Suggested Attributes engine is used See the Developer's Guide for additional details. |
| GetRecommendationsResponseContainer .ProductRecommendations .Product [ attribute productInfoID ] |
string | Conditionally | Unique identifier for the product. See the Developer's Guide for information about eBay product IDs. If the primary and secondary category are both catalog-enabled, this ID corresponds to the primary category. |
|
GetRecommendationsResponseContainer .ProductRecommendations .Product.ProductState |
ProductStateCodeType | Conditionally |
Indicates that the product has changed or will soon change (usually due to a migration from one catalog to another catalog). Typically, this field is returned for up to 90 days for a given product. After that, the product either no longer returns this field or the product is no longer returned (depending on the state change). This data is primarily applicable to catalogs used by the US, Germany, Austria, and Switzerland sites. Other sites may undergo catalog changes in the future. Applicable values: • CustomCode (out) Reserved for internal or future use. • Delete (out) This product is marked for deletion, and it will not be mapped to another product. You cannot add or relist items that use products marked for deletion. If your application currently uses the product for listing or searching, we recommend that you update your application to use a product that is not scheduled to be merged or deleted. • Merge (out) Some information in this product is scheduled to be merged into another product in the catalog that eBay (or Half.com) is currently using. This product may be removed from the system at any time. If your application currently uses the product for listing or searching, we recommend that you update your application to use a product that is not scheduled to be merged or deleted. • Update (out) This product's details have been updated. If your application currently uses the product for listing or searching, we recommend that you check to make sure the product data still meets your needs. • UpdateMajor (out) This product has changed. This product has been mapped to a newer product in the catalog that eBay (or Half.com) is currently using, and its details have been updated based on the new catalog data. The product reference ID remains the same (but the longer product ID string may have changed). If your application currently uses the product for listing or searching, we recommend that you check to make sure the product data still meets your needs. • UpdateNoDetails (out) This product was previously available in an earlier catalog, but it has not been mapped to a product in the catalog that eBay is currently using. It can still be used to pre-fill listings, but it may contain fewer details than other products. If your application currently uses the product for listing or searching, we recommend that you check to make sure the product data still meets your needs. Not applicable to Half.com. |
|
GetRecommendationsResponseContainer .ProductRecommendations .Product.Title |
string | Conditionally |
Title associated with the product. This value can be used as the basis for a suggested listing title. If the title is longer than 80 characters, your application should make sure the suggested title has a maximum length of 80 characters so that it will be valid for the AddItem family of calls. Note: The maximum length of an eBay Item Title has increased to 80 characters as of September 2011. Max length: 1024. |
|
GetRecommendationsResponseContainer .Recommendations |
RecommendationsType | Conditionally |
Contains custom Item Specifics suggestions returned from the custom Item Specifics recommendation engine, An Item Specific consists of a name/value pair, and it may be returned as complete (with name and one or more values) or partial (name only). Only returned when RecommendationEngine=ItemSpecifics. |
|
GetRecommendationsResponseContainer .Recommendations.CategoryID |
string | Conditionally |
The leaf category in which the associated Item Specifics are popular. This is always a category that you specified in the request. Only returned for categories that have popular Item Specifics, or when you also pass in the Name field. Max length: 10. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation |
NameRecommendationType | Conditionally,
repeatable: [0..*] |
Contains an Item Specific that eBay recommends as popular within the specified category. Only returned if recommendations are found. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation.HelpText |
string | Conditionally | Help-text defines the purpose of the tag. The help text will be shown only when it is available for the particular tag |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation.HelpURL |
anyURI | Conditionally | A page on the eBay Web site with context-specific help tips that provide useful information about this Item Specific. Only returned when an applicable page is available in the system. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation.Name |
string | Conditionally | A recommended Item Specific name. Always returned when NameRecommendation is returned. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules |
RecommendationValidationRulesType | Conditionally | Constraints that eBay places on this Item Specific. Always returned when NameRecommendation is returned. As a general rule, AddItem and related calls will not be blocked if you don't use eBay's recommendations, except where specified in this documentation. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules.Confidence |
int | Conditionally |
Indicates eBay's confidence that this is the right name or value, given the data you specified your request. The confidence is based on historical items in the same category, with similar titles (if specified). For example, in GetItemRecommendations, if your request includes a title with words like "Blue T-Shirt", then Color=Blue is likely to have a higher confidence score than Color=Red in the response. If the title does not include a recognized color value, then Color may still have a high confidence score (based on historical item data in the category), but the scores for Blue and Red may have a more even distribution. Only returned when IncludeConfidence is true in the request. Not returned when SelectionMode is Prefilled. Min: 0. Max: 100. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules.MaxValues |
int | Conditionally |
Maximum number of values that you can specify for this Item Specific in listing requests (like AddItem) in the specified category. Most Item Specifics can only have one value. When this is greater than 1, your application can present the value recommendations (if any) as a multi-select list to the seller. (See SelectionMode to determine whether the seller needs to choose from eBay's recommendations or not.) Default: 1. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules.MinValues |
int | Conditionally |
Minimum number of values that you can specify for this Item Specific in listing requests. Not returned if zero (0). If 1 or more, it means this Item Specfic is required in listing requests (in the specified category). (Your listing request will return errors if the Item Specific is not present.) If Relationship is also present, it means this Item Specific is required when you specify its parent value in listing requests. Default: 0. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules.Relationship |
NameValueRelationshipType | Conditionally,
repeatable: [0..*] |
Indicates the Item Specific's logical dependency on another Item Specific, if any. For example, in a clothing category, Size Type could be recommended as a parent of Size, because Size=XL would mean something different to buyers when Size Type=Juniors or Size Type=Regular. Or in the US (in the future), a list of cities can vary depending on the state, so State could be recommended as a parent of City. Currently, categories only recommend a maximum of one parent for an Item Specific. For example, Size=XL could have a Size Type=Juniors parent in a Juniors clothing category. In the future, some categories may recommend multiple parents. For example, City=Mountain View could have parents like State=California, State=New York, and State=North Carolina. If an Item Specific has value dependencies (i.e., if it has value recommendations that contain Relationship), then all of its value recommendations are returned (regardless of the number you specified in MaxValuesPerName). |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules.Relationship .ParentName |
string | Conditionally | The name of another Item Specific that the current value depends on. For example, in a clothing category, "Size Type" could be recommended as a parent of Size. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules.SelectionMode |
SelectionModeCodeType | Conditionally |
Controls whether you can specify your own name and value in listing requests, or if you need to use a name and/or value that eBay has defined. Default: FreeText. Applicable values: • FreeText (out) In listing requests, specify any name or value, or select from the list of recommended values, if present. This is used in most cases. • Prefilled (out) In listing requests, do not specify the name or value because they will be filled in by eBay. In GetItemRecommendations, this indicates that the Item Specific will be pre-filled from a catalog, based on a product ID that you passed in the request. They should be presented as read-only to the seller. If you specify a prefilled value in your listing request when you list with a catalog product, eBay drops the value and uses the value from the catalog instead. • SelectionOnly (out) In listing requests, only specify a value that eBay has recommended. That is, select from the list of recommended values; don't specify your own custom details. If you specify a different value, the listing request may return errors. Rarely used. (Not all values in SelectionModeCodeType apply to this field.) |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules.ValueFormat |
ValueFormatCodeType | Conditionally |
The format of the data type (e.g., date format) that eBay expects the item specific's value to adhere to in listing requests. A data type identified by the ValueType field may have different representations, and ValueFormat specifies the precise format that is required.
Applicable values: • CustomCode (out) Reserved for future use. • FullDate (out) A date in the string format YYYYMMDD • PartialDate (out) A date in the format YYYYMM • Year (out) A date in the format YYYY |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules.ValueType |
ValueTypeCodeType | Conditionally |
The data type (e.g., decimal) that eBay expects the value to adhere to in listing requests. Only returned if the data type is not Text. In some cases, more details about the data type are returned in the ValueFormat field. As buyers may search on the value you specify in AddItem, the ISBN, UPC, or EAN should match the value that was specified by the publisher or manufacturer. Default: Text. Applicable values: • CustomCode (out) Reserved for future use. • Date (out) A Date value, which can assume one of these formats: YYYYMMDD, YYYYMM, or YYYY. See ValueFormat for the recommended format to use in listings. • Decimal (out) A number with a possible decimal point, e.g. -3.14159. (Item Specifics don't distinguish between float and double.) • EAN (out) European Article Number. Max length 13. • ISBN (out) International Standard Book Number (ISBN). ISBNs can contain either 10 or 13 characters. Max length 13. • Text (out) Free-form text. This is the default. Max length 50 (see GeteBayDetails). • UPC (out) Universal Product Code. Max length 12. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules .VariationPicture |
VariationPictureRuleCodeType | Conditionally |
Indicates whether the name (e.g., Color) can (or must) be used to classify the variation pictures.
Applicable values: • CustomCode (out) Reserved for future use. • Disabled (out) The name cannot be used as the Pictures.VariationSpecificName. • Enabled (out) If the name is used in VariationSpecifics, then it can be used as the Pictures.VariationSpecificName. This is the default for variation-enabled categories. • Required (out) If the name is used in VariationSpecifics, then it must be used as the Pictures.VariationSpecificName. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValidationRules .VariationSpecifics |
VariationSpecificsRuleCodeType | Conditionally |
Indicates whether the recommended name/value pair can be used in Item.Variations in AddFixedPriceItem and related calls. For example, a given category could disable a name like Brand in variation specifics (if Brand is only allowed in the item specifics at the Item level). The same category could enable a name like Size for variation specifics (in addition to recommending it for item specifics). If not returned, then the name/value can be used for both variation specifics and item specifics.
Applicable values: • CustomCode (out) Reserved for future use. • Disabled (out) The recommended name/values can't be used in VariationSpecifics (but they can be used in ItemSpecifics). Typically, this occurs when the category doesn't support variations, or if the category requires the name to be the same for all variations in the listing. • Enabled (out) The recommended name (and values, if any) can be used either in the Item Specifics or VariationSpecifics context in listing calls. This is the default for variation-enabled categories. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValueRecommendation |
ValueRecommendationType | Conditionally,
repeatable: [0..*] |
A recommended value (if any) for the Item Specific name. Only returned when a recommended value is available in the system. If an Item Specific has value dependencies (i.e., if it has value recommendations that contain Relationship), then all of its value recommendations are returned. If it has no dependencies, then the maximum number of value recommendations that can be returned is limited by the number you specified in MaxValuesPerName. See MaxValuesPerName. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValueRecommendation .ValidationRules |
RecommendationValidationRulesType | Conditionally |
Constraints that eBay places on this Item Specific value. Only returned when you configure your request to include relationships and/or confidence, and a recommended value is available. (Not returned when ExcludeRelationships is true and IncludeConfidence is false.) |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValueRecommendation .ValidationRules.Confidence |
int | Conditionally |
Indicates eBay's confidence that this is the right name or value, given the data you specified your request. The confidence is based on historical items in the same category, with similar titles (if specified). For example, in GetItemRecommendations, if your request includes a title with words like "Blue T-Shirt", then Color=Blue is likely to have a higher confidence score than Color=Red in the response. If the title does not include a recognized color value, then Color may still have a high confidence score (based on historical item data in the category), but the scores for Blue and Red may have a more even distribution. Only returned when IncludeConfidence is true in the request. Not returned when SelectionMode is Prefilled. Min: 0. Max: 100. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValueRecommendation .ValidationRules.Relationship |
NameValueRelationshipType | Conditionally,
repeatable: [0..*] |
Indicates the Item Specific's logical dependency on another Item Specific, if any. For example, in a clothing category, Size Type could be recommended as a parent of Size, because Size=XL would mean something different to buyers when Size Type=Juniors or Size Type=Regular. Or in the US (in the future), a list of cities can vary depending on the state, so State could be recommended as a parent of City. Currently, categories only recommend a maximum of one parent for an Item Specific. For example, Size=XL could have a Size Type=Juniors parent in a Juniors clothing category. In the future, some categories may recommend multiple parents. For example, City=Mountain View could have parents like State=California, State=New York, and State=North Carolina. If an Item Specific has value dependencies (i.e., if it has value recommendations that contain Relationship), then all of its value recommendations are returned (regardless of the number you specified in MaxValuesPerName). |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValueRecommendation .ValidationRules.Relationship .ParentName |
string | Conditionally | The name of another Item Specific that the current value depends on. For example, in a clothing category, "Size Type" could be recommended as a parent of Size. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValueRecommendation .ValidationRules.Relationship .ParentValue |
string | Conditionally | The value of another Item Specific that the current value depends on. For example, in a clothing category, if "Size Type" is the ParentName, then "Petite" could be recommended as a parent value for Size=Medium. |
|
GetRecommendationsResponseContainer .Recommendations .NameRecommendation .ValueRecommendation.Value |
string | Conditionally | A recommended value for the Item Specific. Only returned when a recommended value is available. |
|
GetRecommendationsResponseContainer .Title |
string | Conditionally |
The recommended title of the item listing. Note: The maximum length of an eBay Item Title has increased to 80 characters as of September 2011. Max length: 80. |
| Input Output Samples Change History Top Errors for GetItemRecommendations User Notes |
This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.
| Input Output Detail Controls Change History Top Errors for GetItemRecommendations User Notes |
New to making API calls? Please see Routing the Request.
Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.
Retrieves recommended Item Specifics based on a leaf category and title.
Description
This sample retrieves recommended Item Specifics for KitchenAid blender on the eBay US site. If recommendations are available for the category, each NameRecommendation node returns the recommended name, validation rules, and recommended values (if any). (Categories that support custom Item Specifics do not necessarily have recommendations. So, this call does not always return data.)
Input
The key inputs for this sample are Title and CategoryID. For the recommendations to be useful in listing calls, category ID must be a leaf category that is flagged as ItemSpecificsEnabled according to GetCategoryFeatures. In this sample, the title contains the keyword "KitchenAid". In addition, IncludeConfidence is passed in the request to help the seller decide which recommendation might be the best fit. The request version (in the HTTP header) is 609 (not shown).
Please note that this sample was created based on a test category (Test Blenders), so this category does not return any recommendations in the Sandbox or in Production. A new sample will be created based on production data in a future release.
XML format (HTTP POST). Also available is the .txt version of this XML. <GetItemRecommendationsRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <GetRecommendationsRequestContainer> <RecommendationEngine>ItemSpecifics</RecommendationEngine> <Item> <PrimaryCategory> <CategoryID> 20668 </CategoryID> </PrimaryCategory> <Title> KitchenAid Blender </Title> </Item> <IncludeConfidence>true</IncludeConfidence> <CorrelationID>1</CorrelationID> </GetRecommendationsRequestContainer> <RequesterCredentials> <eBayAuthToken>ABC...123</eBayAuthToken> </RequesterCredentials> <WarningLevel>High</WarningLevel> </GetItemRecommendationsRequest>
Output
In the output, each NameRecommendation node returns the recommended names and validation rules for two Item Specifics (Color and Brand). One of the recommendations also returns two ValueRecommendation nodes with recommended values (KitchenAid and The Magic Bullet).
The validation rules indicate that the Item Specifics are optional in listing calls (MinValues is not returned), only one value is allowed per Item Specific (MaxValues is 1), and you can use one of the recommended values or specify a custom value (SelectionMode is FreeText). The KitchenAid value is more strongly recommended Confidence is 99), due to the presence of the keyword "KitchenAid" in the requested title.
If you try a leaf category and you get no results, it could be because there are no recommendations in that category. Also make sure you are using request version 609 or higher, and make sure the category supports custom Item Specifics.
XML format. Also available is the .txt version of this XML. <GetItemRecommendationsResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2012-05-15T07:06:03.103Z</Timestamp> <Ack>Success</Ack> <Version>771</Version> <Build>E771_CORE_BUNDLED_14831195_R1</Build> <GetRecommendationsResponseContainer> <CorrelationID>1</CorrelationID> </GetRecommendationsResponseContainer> </GetItemRecommendationsResponse>
| Input Output Detail Controls Samples Top Errors for GetItemRecommendations User Notes |
| Version | Description |
|---|---|
| 757 2012-01-18 |
|
| 743 2011-10-12 |
|
| 735 2011-08-17 |
|
| 729 2011-07-06 |
|
| 719 2011-04-27 |
|
| 675 2010-06-23 |
|
| 663 2010-03-31 |
|
| 661 2010-03-17 |
|
| 635 2009-09-16 |
|
| 615 2008-04-29 |
|
| 609 2009-03-18 |
|
| 605 2009-02-18 |
|
| 599 2009-1-07 |
|
| 573 2008-07-09 |
|
| 565 2008-05-14 |
|
| 561 2008-04-16 |
|
| 537 2007-10-31 |
|
| All Versions All Dates |
|
| 521 2007-07-11 |
|
| 471 2006-7-26 |
|
| Input Output Detail Controls Samples Change History Top Errors for GetItemRecommendations User Notes |
Copyright © 2005–2012 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.