eBay Trading API
|
| Note: This API call is being deprecated and will not be available after July 1, 2010. The functionality provided by this call will be supported in the new Finding API. If you're building new search applications, we recommend you start with the Finding API. |
See:
Finding All Item Listings in a Specified Category
GetCategoryListings
Introduction to Pictures in Item Listings
| Output Detail Controls Samples Change History Top Errors for GetCategoryListings |
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"?>
<GetCategoryListingsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
<!-- Standard Input Fields -->
<ErrorLanguage> string </ErrorLanguage>
<MessageID> string </MessageID>
<OutputSelector> string </OutputSelector>
<!-- ... more OutputSelector nodes here ... -->
<Version> string </Version>
<WarningLevel> WarningLevelCodeType </WarningLevel>
<!-- Call-specific Input Fields -->
<AdFormat> boolean </AdFormat>
<CategoryID> string </CategoryID>
<Currency> CurrencyCodeType </Currency>
<FreeShipping> boolean </FreeShipping>
<Group> GroupType
<MaxEntriesPerGroup> int </MaxEntriesPerGroup>
<MaxGroups> int </MaxGroups>
</Group>
<HideDuplicateItems> boolean </HideDuplicateItems>
<IncludeCondition> boolean </IncludeCondition>
<IncludeFeedback> boolean </IncludeFeedback>
<IncludeGetItFastItems> boolean </IncludeGetItFastItems>
<ItemTypeFilter> ItemTypeFilterCodeType </ItemTypeFilter>
<LocalSearchPostalCode> string </LocalSearchPostalCode>
<MaxRelatedSearchKeywords> int </MaxRelatedSearchKeywords>
<MotorsGermanySearchable> boolean </MotorsGermanySearchable>
<OrderBy> CategoryListingsOrderCodeType </OrderBy>
<Pagination> PaginationType
<EntriesPerPage> int </EntriesPerPage>
<PageNumber> int </PageNumber>
</Pagination>
<PaymentMethod> PaymentMethodSearchCodeType </PaymentMethod>
<ProximitySearch> ProximitySearchType
<MaxDistance> int </MaxDistance>
<PostalCode> string </PostalCode>
</ProximitySearch>
<SearchLocation> SearchLocationType
<RegionID> string </RegionID>
<SiteLocation> SiteLocationType
<SiteID> SiteIDFilterCodeType </SiteID>
</SiteLocation>
</SearchLocation>
<SearchType> CategoryListingsSearchCodeType </SearchType>
</GetCategoryListingsRequest>
| 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. |
| OutputSelector | string | Optional,
repeatable: [0..*] |
You can use the OutputSelector field to restrict the data returned by this call. When you make a call such as GetItem that retrieves data from eBay, the OutputSelector field is useful for restricting the data returned. This field makes the call response easier to use, especially when a large payload would be returned. If you use the OutputSelector field, the output data will include only the fields you specified in the request. For example, if you are using GetItem and you want the item data in the response to be restricted to the ViewItemURL (the URL where a user can view the listing) and BuyItNowPrice, then within the GetItem request, specify those output fields. To use this field, see the information at the following link. |
| 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 | |||
| AdFormat | boolean | Optional | Restricts listings to return only items that have the Ad Format feature. If true, the values of ItemTypeFilter and StoreSearchFilter are ignored (if they are specified). That is, "AND" logic is not applied. |
| CategoryID | string | Required |
Specifies the category for which to retrieve item listings. Max length: 10. |
| Currency | CurrencyCodeType | Optional |
A currency value. Limits the result set to just those items listed using a specified currency. Not applicable to US eBay Motors searches.
Applicable values: See Currency. |
| FreeShipping | boolean | Optional |
If true, only items with free shipping for the user's location are returned. The user's location is determined from the site ID specified in the request. If false, no filtering is done via this attribute. A listing is not considered a free shipping listing if it requires insurance or requires pick up or requires a shipping surcharge. Default: false. |
| Group | GroupType | Optional | You can group Best Match search results by category. To group by category, put the BestMatchCategoryGroup value in the OrderBy field. When you use the BestMatchCategoryGroup value, you can include group parameters in your call. Note that there will be significanty fewer results returned with a BestMatchCategoryGroup sort because the results account for Best Matches in lower-level (leaf) as well as higher-level categories. There is not a direct correlation between the number of results returned in a regular sort or the number of results returned with a BestMatch sort, and the results that are returned by the BestMatchCategoryGroup sort. You should not receive more than 2 pages of results with this type of sort. See also the new GroupCategoryID element in ItemType. |
| Group.MaxEntriesPerGroup | int | Optional | Use a positive whole number to specify the maximum number of entries per group that you want to include in the search result. |
| Group.MaxGroups | int | Optional | Use a positive whole number to specify the maximum number of groups that you want to include in the search result. |
| HideDuplicateItems | boolean | Optional |
Specifies whether or not to remove duplicate items from search results. When set to true, and there are duplicate items for an item in the search results, the subsequent duplicates will not appear in the results. Item listings are considered duplicates in the following conditions:
For Auctions, items must also have the same price and number of bids to be considered duplicates. Filtering of duplicate item listings is not supported on all sites. Default: false. |
| IncludeCondition | boolean | Optional | If true, each item in the result set can also include the item condition (whether the item is new or used). The item's condition is returned in Item.AttributeSetArray. An item only includes condition attribute if the item's seller filled in the Item Condition in the Item Specifics section of the listing. (That is, the condition is not returned if the seller only put the word "New" in the listing's title.) |
| IncludeFeedback | boolean | Optional | If true, each item in the result set also includes information about the seller's feedback. |
| IncludeGetItFastItems | boolean | Optional | When passed with a value of true, limits the results to Get It Fast listings. |
| ItemTypeFilter | ItemTypeFilterCodeType | Optional |
Filters items based on the ListingType set for the items. If ItemTypeFilter is not specified (or if the AllItemTypes value of ItemTypeFilter is specified), all listing types can be returned unless another relevant filter is specified.
Applicable values: • AllFixedPriceItemTypes (in) Retrieves fixed-price items. Whether StoresFixedPrice items are retrieved does not depend on the site default. The StoresFixedPrice items are retrieved after the basic fixed price items. Items are retrieved whether or not ListingType is set to StoresFixedPrice. Does not retrieve items for which ListingType is AdType. Does not retrieve auction items for which BuyItNowEnabled is false. • AllItems (in) It is recommended that you use AllItemTypes instead of AllItems. Return all listing types (the default for GetSearchResults). Whether StoresFixedPrice items are retrieved depends on the site default. • AllItemTypes (in) Retrieve listings whether or not ListingType is set to StoresFixedPrice; include auction items. • AuctionItemsOnly (in) Retrieve only listings eligible for competitive bidding at auction. That is, only retrieve listings for which ListingType is Chinese (single-item auction), regardless of the BuyItNowEnabled value. Items with any of the following listing types are not retrieved: StoresFixedPrice, FixedPriceItem, and AdType. • ClassifiedItemsOnly (in) Only retrieve Classified Ad format listings. • CustomCode (in) Reserved for internal or future use. • ExcludeStoreInventory (in) Exclude listings that have ListingType set to StoresFixedPrice. • FixedPricedItem (in) Retrieves only listings that can be purchased at a fixed price. That is, only retrieves listings for which ListingType is StoresFixedPrice or FixedPriceItem. Whether StoresFixedPrice items are retrieved depends on the site default. If StoresFixedPrice items are retrieved, they are returned after the other retrieved items. Also retrieves competitive-bid auction listings for which BuyItNowEnabled is true. Does not retrieve listings for which ListingType is AdType, and does not retrieve auction listings for which BuyItNowEnabled is false. • FixedPriceExcludeStoreInventory (in) Exclude listings that have ListingType set to StoresFixedPrice. Exclude listings that have ListingType set to AdType. Exclude auction listings in which BuyItNowEnabled is false. • StoreInventoryOnly (in) Only retrieve listings for which ListingType is StoresFixedPrice. |
| LocalSearchPostalCode | string | Optional | Include local items in returning results near this postal code. This postal code is the basis for local search. |
| MaxRelatedSearchKeywords | int | Optional |
The maximum number of related keywords to be retrieved. Use this field if you want the results to include recommended keywords (that is, keywords matching the category ID) in a RelatedSearchKeywordArray container. A value of 0 (the default) means no related search information is processed. Min: 0. Max: 100. |
| MotorsGermanySearchable | boolean | Optional | Filters the response based on each item's eligibility to appear on the mobile.de site. If false, excludes eligible items from search results. If true, queries for eligible items only. If not specified, the search results are not affected. Only applicable for items listed on the eBay Germany site (site ID 77) in subcategories of mobile.de search-enabled categories. |
| OrderBy | CategoryListingsOrderCodeType | Optional |
Specifies the order in which the item listings returned will be sorted. Store Inventory listings are usually returned after other listing types, regardless of the sort order. Default: BestMatchSort. Applicable values: • BestMatchCategoryGroup (in) Groups Best Match search results by category. See BestMatchSort. You can also set the number of groups and items per group within the Group section of the call. If you specify BestMatchCategoryGroup, and you want to specify a value for Pagination.EntriesPerPage, the Pagination.EntriesPerPage value can be 50 or less. • BestMatchSort (in) Sorts items by Best Match, which is based on community buying activity and other relevance-based factors. • CustomCode (in) Reserved for internal or future use. • DistanceSort (in) Sort items by distance • ItemsBy24Hr (in) Returns items that were listed in the past 24 hours. • ItemsEndIn5Hr (in) Reserved for internal use. • ItemsEndToday (in) Reserved for internal use. • NoFilter (in) Applies no filter. • PricePlusShippingAsc (in) This field is part of the Price Plus Shipping Sort feature, to be enabled by the end of Sept. 2007 for the following sites: US (site ID 0), Germany (77), Canada (2), and Australia (15). The Price Plus Shipping Sort feature causes item sorting to consider shipping costs. Specify PricePlusShippingAsc to sort items by lowest cost first, as follows: Lowest-total-cost (for items where shipping was properly specified), then freight-shipping items, then items for which shipping was not specified (sorted by price). • PricePlusShippingDesc (in) This field is part of the Price Plus Shipping Sort feature, to be enabled by the end of Sept. 2007 for the following sites: US (site ID 0), Germany (77), Canada (2), and Australia (15). The Price Plus Shipping Sort feature causes item sorting to consider shipping costs. Specify PricePlusShippingDesc to sort items by highest cost first, as follows: highest-total-cost (for items where shipping was properly specified), then freight-shipping items, then items for which shipping was not specified (sorted by price). • SortByPriceAsc (in) Sort items by price (lowest first) • SortByPriceDesc (in) Sort items by price (highest first) |
| Pagination | PaginationType | Optional | Controls the pagination of the result set. Child elements specify the maximum number of item listings to return per call and which page of data to return. |
| Pagination.EntriesPerPage | int | Optional | Specifies the maximum number of entries to return in a single call. If the number of entries that can be returned is less than the value in EntriesPerPage, then the lower number is returned. For most calls, the max is 200 and the default is 25. For GetUserDisputes, the value is hard-coded at 200, and any input is ignored. For GetProducts, the maximum is 20 (and higher values are ignored). See the annotations for other individual calls to determine the correct max and default values. For GetOrders, not applicable to eBay.com (but applicable to Half.com for GetOrders). |
| Pagination.PageNumber | int | Optional |
Specifies the number of the page of data to return in the current call. Default is 1 for most calls. For some calls, the default is 0. Specify a positive value equal to or lower than the number of pages available (which you determine by examining the results of your initial request). See the documentation for other individual calls to determine the correct default value. For GetOrders, not applicable to eBay.com (for GetOrders, applicable to Half.com). Min: 1. Default: 1. |
| PaymentMethod | PaymentMethodSearchCodeType | Optional |
Specifies items that accept a specific payment method or methods.
Applicable values: • CustomCode (in/out) • PaisaPay (in/out) PaisaPay payment method. The PaisaPay payment method is only for the India site (site ID 203). • PaisaPayEscrowEMI (in/out) PaisaPayEscrowEMI (Equal Monthly Installments) payment method. The PaisaPayEscrowEMI payment method is only for the India site (site ID 203). • PayPal (in/out) PayPal payment method. • PayPalOrPaisaPay (in/out) Either the PayPal or the PaisaPay payment method. The PaisaPay payment method is only for the India site (site ID 203). |
| ProximitySearch | ProximitySearchType | Optional | Limits the result set to just those items that meet proximity search criteria: postal code and max distance. |
| ProximitySearch.MaxDistance | int | Optional | The maximum distance from the specified postal code to search for items. |
| ProximitySearch.PostalCode | string | Optional | The postal code to use as the basis for the proximity search. |
| SearchLocation | SearchLocationType | Optional | Limits the result set to just those items that meet location criteria: listed in a specified eBay site, location where the seller has the item, location from which the user is searching, and/or items listed with a specified currency. |
| SearchLocation.RegionID | string | Optional | Specifies a region ID. The item must have been listed for the specified region to be returned in the search result set. |
| SearchLocation.SiteLocation | SiteLocationType | Optional | Specifies a filter based on a particular eBay site and the item's relation to that site (items listed with a site's currency, items located in the country for the site, items available to the country for the site, and items listed on the specified site). |
|
SearchLocation.SiteLocation .SiteID |
SiteIDFilterCodeType | Optional |
Specifies the criteria for filtering search results by site, where site is determined by the site ID in the SOAP URL or, for Unified Schema XML requests, X-EBAY-API-SITEID HTTP Header.
Applicable values: • AvailableInCountryImplied (in) Items available to the country implied by the site specified in the request. For the US site, this implies listings from ALL English-language countries that are available to the US. • BelgiumListing (in) Items located in Belgium or listed on one of the two Belgian sites. • CustomCode (in) Reserved for internal or future use. • ListedInCurrencyImplied (in) Items listed in the currency implied by the site specified in the request. • LocatedInCountryImplied (in) Items located in the country implied by the site specified in the request. • SiteImplied (in) Items listed on the site specified in the request, regardless of listing currency. |
| SearchType | CategoryListingsSearchCodeType | Optional |
Specifies whether to limit the item listings to just those that are category featured or super featured or all items.
Applicable values: • CustomCode (in) Reserved for internal or future use. • Featured (in) Return only featured item listings. • SuperFeatured (in) Return only super-featured item listings. |
| Input Detail Controls Samples Change History Top Errors for GetCategoryListings |
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"?>
<GetCategoryListingsResponse 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 -->
<BuyingGuideDetails> BuyingGuideDetailsType
<BuyingGuide> BuyingGuideType
<CategoryID> string </CategoryID>
<Name> string </Name>
<URL> anyURI </URL>
</BuyingGuide>
<!-- ... more BuyingGuide nodes here ... -->
<BuyingGuideHub> anyURI </BuyingGuideHub>
</BuyingGuideDetails>
<Category> CategoryType
<CategoryID> string </CategoryID>
<CategoryName> string </CategoryName>
</Category>
<DuplicateItems> boolean </DuplicateItems>
<HasMoreItems> boolean </HasMoreItems>
<ItemArray> ItemArrayType
<Item> ItemType
<AttributeSetArray> AttributeSetArrayType
<AttributeSet attributeSetID="int"> AttributeSetType
<Attribute attributeID="int" attributeLabel="string"> 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>
<BestOfferEnabled> boolean </BestOfferEnabled>
<BuyItNowPrice> AmountType (double) </BuyItNowPrice>
<Currency> CurrencyCodeType </Currency>
<Distance> DistanceType
<DistanceMeasurement> int </DistanceMeasurement>
<DistanceUnit> string </DistanceUnit>
</Distance>
<ListingDetails> ListingDetailsType
<ConvertedBuyItNowPrice> AmountType (double) </ConvertedBuyItNowPrice>
<EndTime> dateTime </EndTime>
<StartTime> dateTime </StartTime>
<ViewItemURL> anyURI </ViewItemURL>
<ViewItemURLForNaturalSearch> anyURI </ViewItemURLForNaturalSearch>
</ListingDetails>
<ListingEnhancement> ListingEnhancementsCodeType </ListingEnhancement>
<!-- ... more ListingEnhancement nodes here ... -->
<ListingType> ListingTypeCodeType </ListingType>
<LocalListing> boolean </LocalListing>
<Location> string </Location>
<MotorsGermanySearchable> boolean </MotorsGermanySearchable>
<PictureDetails> PictureDetailsType
<GalleryType> GalleryTypeCodeType </GalleryType>
<GalleryURL> anyURI </GalleryURL>
</PictureDetails>
<Seller> UserType
<FeedbackPrivate> boolean </FeedbackPrivate>
<FeedbackScore> int </FeedbackScore>
<PositiveFeedbackPercent> float </PositiveFeedbackPercent>
</Seller>
<SellingStatus> SellingStatusType
<BidCount> int </BidCount>
<ConvertedCurrentPrice> AmountType (double) </ConvertedCurrentPrice>
<CurrentPrice> AmountType (double) </CurrentPrice>
</SellingStatus>
<Site> SiteCodeType </Site>
<SubTitle> string </SubTitle>
<Title> string </Title>
</Item>
<!-- ... more Item nodes here ... -->
</ItemArray>
<ItemsPerPage> int </ItemsPerPage>
<PageNumber> int </PageNumber>
<PaginationResult> PaginationResultType
<TotalNumberOfEntries> int </TotalNumberOfEntries>
<TotalNumberOfPages> int </TotalNumberOfPages>
</PaginationResult>
<RelatedSearchKeywordArray> RelatedSearchKeywordArrayType
<Keyword> string </Keyword>
<!-- ... more Keyword nodes here ... -->
</RelatedSearchKeywordArray>
<SubCategories> CategoryArrayType
<Category> CategoryType
<CategoryID> string </CategoryID>
<CategoryName> string </CategoryName>
</Category>
<!-- ... more Category nodes here ... -->
</SubCategories>
</GetCategoryListingsResponse>
| 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 | |||
| BuyingGuideDetails | BuyingGuideDetailsType | Conditionally | Contains information about relevant buying guides (if any) and the site's buying guide hub. Buying guides are useful to buyers who do not have a specific product in mind. For example, a digital camera buying guide could help a buyer determine what kind of digital camera is right for them. |
| BuyingGuideDetails.BuyingGuide | BuyingGuideType | Conditionally,
repeatable: [0..*] |
Information that identifies a buying guide. A buying guide contains content about particular product areas, categories, or subjects to help buyers decide which type of item to purchase based on their particular interests. Buying guides are useful to buyers who do not have a specific product in mind. For example, a digital camera buying guide could help a buyer determine what kind of digital camera is right for them. |
|
BuyingGuideDetails.BuyingGuide .CategoryID |
string | Conditionally |
Identifies the category (if any) that is associated with the buying guide. For GetSearchResults, this can be a category that is higher or lower in the hierarchy than the category specified in the request. For a matching categories search, you can use this information to determine the order that the buying guides are returned in when multiple guides are found. Optionally, you can use this information to determine where to present the buying guide link in your application. Not returned for product finder searches. Max length: 10. |
|
BuyingGuideDetails.BuyingGuide .Name |
string | Conditionally |
Display name of the buying guide. GetProducts only returns 20 characters, followed by "..." if the name is longer than 20 characters. For the full title, see BuyingGuide.Title instead. |
|
BuyingGuideDetails.BuyingGuide .URL |
anyURI | Conditionally | URL for the buying guide. Your application can present this as a link. Use the value of Name as the link's display name. |
|
BuyingGuideDetails .BuyingGuideHub |
anyURI | Conditionally | URL of the buying guide home page for the site being searched. Your application can present this URL as a link. Optionally, you can use a value like "See all buying guides" as the link's display name. GetProducts returns this URL even when no guides are available for the product. |
| Category | CategoryType | Always | Indicates the category from which the listings were drawn. |
| Category.CategoryID | string | Always |
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. |
| Category.CategoryName | string | Always |
Display name of the category as it would appear on the eBay Web site. In GetItem, this is a fully qualified category name (e.g., Collectibles:Decorative Collectibles:Hummel, Goebel). In GetItem, always returned for eBay.com listings. Not returned in PrimaryCategory for Half.com listings. Max length: 30. |
| DuplicateItems | boolean | Conditionally | Indicates whether there are duplicated items not returned by this response when HideDuplicateItems is true in the request. |
| HasMoreItems | boolean | Always | Indicates whether there are more item listings that can be returned (items listed in the specified category and that meet any input filtering criteria). |
| ItemArray | ItemArrayType | Conditionally | Contains the item listings for the specified category and which meet the input filtering criteria (if any is specified). Consists of one ItemType object for each returned item listing. |
| ItemArray.Item | ItemType | Conditionally,
repeatable: [0..*] |
Contains the data properties that define one item listing. GetSellerEvents and GetSellerList only return items if any are available for the seller within the time window specified in the request. Some optional fields are only returned if the seller defined them for the item. Some fields are only returned under particular conditions specified in the individual field descriptions. For example, a buyer's contact information might only be returned if the member who is making the request (as identified in eBayAuthToken) has a transactional relationship with that buyer. For calls that support detail levels, the set of fields returned is also controlled by the value of DetailLevel in the request. For some calls, other parameters in the request can also control the data returned for each item. For example, GranularityLevel controls the fields to return for each item in the GetSellerList response. |
|
ItemArray.Item .AttributeSetArray |
AttributeSetArrayType | Conditionally |
AttributeSetArray is one format that is used to to specify Item Specifics on the eBay Web site. (Also see Item.ItemSpecifics.) Item Specifics describe an item in a standard way so that buyers can find it more easily. For example, "Publication Year" is a standard property of a book. Contains one or more instances of AttributeSet in a list. For attributes in general, an item can be associated with no more than two full attribute sets (one for the primary category and one for the secondary category). For some international sites, an item can specify an additional site-wide attribute set for the item condition. Older applications can still use AttributeSetArray to specify a return policy (which is defined in a site-wide attribute set for most sites). However, as eBay may deprecate return policy attributes in the future, we strongly recommend that you use the new Item.ReturnPolicy node instead to specify the seller's return policy. Note: AttributeSetArray does not support the newer "custom Item Specifics" model. See the ItemSpecifics node instead. For the AddItem family of calls: Some categories (such as Event Tickets and US Real Estate) require Item Specifics. See the eBay Web Services Guide links below for information on working with Item Specifics. Use GetCategory2CS and GetAttributesCS to determine when attributes are required for a category. Also use attributes to specify the item condition. For 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 GetCategoryListings only: For GetCategoryListings, AttributeSetArray can return the item condition (not other Item Specifics), if specified. For GetSearchResults only: GetSearchResults can return the item condition when the request either specifies IncludeCondition as true; or specifies a product finder search (and a detail level of ItemReturnAttributes or ReturnAll). If IncludeCondition was true, see the ItemSpecific node for a simpler view of the condition value. Note: AttributeSetArray only returns the condition attribute's ValueID. You would need to use GetAttributesCS to figure out the meaning of this ID. It's easier to just look at the ItemSpecific node. If SearchRequest or TicketFinder was used to perform a product finder search, the list of attributes is limited to Item Specifics that would be included in the summary search results on the Web site, if any. At this time, GetSearchResults only returns event ticket venue name, section, and row (if specified) for eBay US (site 0); and the mileage and year for eBay Motors vehicles (site 100 and international eBay Motors sites that support this feature). In other categories, no summary attributes are returned in search results (even when the item is listed with Item Specifics.) For GetItemRecommendations only: In GetItemRecommendations, if you use the Suggested Attributes engine, the engine interprets attributes you pass in as attributes that do NOT need recommendations (i.e., attributes that the seller has already filled in as desired). The engine only returns recommendations for attributes that you do not specify, and only for attributes associated with the primary category. For Half.com, this is only returned in GetItem. It is not applicable in AddItem and other requests. See:
|
|
ItemArray.Item .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. |
| ItemArray.Item .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. For GetCategoryListings, you can ignore this value. Not applicable to Half.com. |
|
ItemArray.Item .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 attrribute meta-data, how to determine the valid attributes for a category, and how to determine whether attributes are required. If you are revising or relisting an item, you don't need to pass in attributes that were already specified in the original listing. To remove an optional attribute, set all its value IDs to "-100". If the item has bids (or items have been sold) but there are more than 12 hours remaining until the listing ends, you can add Attribute nodes but you cannot remove or modify data in previously specified Attribute nodes. If the item has bids and the listing ends within 12 hours, you cannot add or remove Attribute nodes or modify the contents of previously specified Attribute nodes. For GetCategoryListings, this returns the item condition only (and it is only returned if IncludeCondition = true in the request). Not applicable to Half.com. |
| ItemArray.Item .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. |
| ItemArray.Item .AttributeSetArray .AttributeSet.Attribute [ attribute attributeLabel ] |
string | Conditionally | Name of the attribute being specified. This is not part of eBay's standard Item Specifics format (i.e., there is no relationship to GetAttributesCS). For GetCategoryListings, this returns the value "Condition" to identify the item condition attribute. For GetOrders, this is always returned for Half.com orders. (It is not applicable to orders on the eBay.com site.) For Half.com, see the eBay Web Services Guide for valid input values. For Half.com, this field is required when you use AddItem. You can revise this value for Half.com listings. |
|
ItemArray.Item .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. |
|
ItemArray.Item .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. |
|
ItemArray.Item .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 GetSearchResults requests (in SearchRequest), only use ValueLiteral for attributes that support free-text values. That is, if eBay defines a value name and a unique value ID for an attribute in GetProductFinder, do not pass the name in ValueLiteral (because it won't work). Instead, specify the unique value ID in ValueID. For Half.com, use AttributeArray.Attribute.Value.ValueLiteral in listing requests. That is, the parent elements and usage for Half.com differs from eBay's standard Item Specifics format (and there is no relationship to GetAttributesCS). For Half.com, AttributeArray.Attribute.Value.ValueLiteral is required when you use AddItem. See the eBay Web Services Guide for valid values. For the Half.com Notes attribute, the max length is 500 characters. You can revise AttributeArray.Attribute.Value.ValueLiteral for Half.com listings. Max length: see description. |
|
ItemArray.Item .BestOfferEnabled |
boolean | Conditionally | Indicates, when true, that an item is available by Best Offer. |
| ItemArray.Item.BuyItNowPrice | AmountType (double) | Conditionally |
For Chinese auction listings, Buy It Now allows a user to purchase the item at a fixed price and end the auction immediately. Use this field to add Buy It Now and specify the amount a buyer would need to bid to take advantage of the Buy It Now feature. On the main eBay site, not applicable to fixed-price items (ListingType values StoresFixedPrice or FixedPriceItem), AdFormat listings, or Half.com listings. For fixed-price and Half.com listings, see StartPrice instead. See the eBay Web Services Guide for validation rules when revising US eBay Motors listings, including rules for lowering the Buy It Now price of a Motors listing. Once a Chinese auction has bids (and the high bid exceeds the reserve price, if specified), the listing is no longer eligible for Buy It Now (with some exceptions noted below). However, calls like GetItem and GetSearchResults still return the BuyItNowPrice that the seller originally set for the listing. You can use Item.SellingStatus.BidCount to determine whether an auction with Buy It Now has bids or not. With GetSearchResults, you can use the Item.SearchDetails.BuyItNowEnabled flag to determine whether the item can still be purchased using Buy It Now. With GetItem, you can use the Item.ListingDetails.BuyItNowAvailable flag to determine whether the item can still be purchased using Buy It Now. On some sites, the Buy It Now price for a Chinese auction may remain available for certain categories even after a bid is placed. See the "Longer Lasting Buy It Now" link below for more details and the latest list of eBay US categories that support this behavior. The eBay Spain site supports this behavior for all categories. 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:
|
| ItemArray.Item.Currency | CurrencyCodeType | Conditionally |
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: See Currency. |
| ItemArray.Item.Distance | DistanceType | Conditionally |
The distance used in a proximity search distance calculation. Not applicable to Half.com. |
|
ItemArray.Item.Distance .DistanceMeasurement |
int | Conditionally | The measurement used in a proximity search distance calculation. |
|
ItemArray.Item.Distance .DistanceUnit |
string | Conditionally | The unit used in a proximity search distance calculation. |
| ItemArray.Item.ListingDetails | ListingDetailsType | Conditionally |
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. |
|
ItemArray.Item.ListingDetails .ConvertedBuyItNowPrice |
AmountType (double) | Conditionally | Converted value of the BuyItNowPrice in the currency of the site that returned this response. For active items, refresh this value every 24 hours to pick up the current conversion rates. |
|
ItemArray.Item.ListingDetails .EndTime |
dateTime | Conditionally |
Time stamp (in GMT) when the listing is scheduled to end (calculated based on the values of StartTime and ListingDuration) or the actual end time if the item has ended. In GetSearchResults, for StoresFixedPrice items which are "Good Till Canceled," this value is 5 minutes later than the actual end time of the item. The discrepancy is intended to facilitate renewal every 30 days of such items' end times. In GetSearchResults, the same EndTime may be returned for multiple results if the results are variations from the same multi-variation listing. |
|
ItemArray.Item.ListingDetails .StartTime |
dateTime | Conditionally | The StartTime value returned by non-search calls such as GetItem is the time stamp (in GMT) for when the item was listed. The StartTime value returned by search calls such as GetSearchResults and GetCategoryListings may vary from the value returned by GetItem. The time value is the same value in the following: The StartTime value returned by GetSearchResults, the StartTime value returned by GetCategoryListings, and the time the item became available for search on the eBay site. |
|
ItemArray.Item.ListingDetails .ViewItemURL |
anyURI | Conditionally |
The URL of the Web page where a user can view the listing. On the US site, this is called the "View Item" page. If you enabled affiliate tracking in a search-related call (for example, if you used the AffiliateTrackingDetails container in an applicable call), ViewItemURL contains a string that includes affiliate tracking information (see the eBay Partner Network). In search results (like the GetSearchResults response), this link to the View Item page is configured to select the applicable variation. |
|
ItemArray.Item.ListingDetails .ViewItemURLForNaturalSearch |
anyURI | Conditionally |
This URL takes you to the same View Item page as ViewItemURL, but this URL is optimized to support natural search. That is, this URL is designed to make items on eBay easier to find via popular Internet search engines. The URL includes the item title along with other optimizations. To note, "?" (question mark) optimizes to "_W0QQ", "&" (ampersand) optimizes to "QQ", and "=" (equals sign) optimizes to "Z". If you are an eBAy affiliate, use this URL to promote your affiliate information. Note: This URL may include additional query parameters that don't appear in ViewItemURL and vice versa. You should not modify the query syntax. For example, eBay won't recognize the URL if you change QQ to ?. In search results (like the GetSearchResults response), if the result is a variation from a multi-variation listing, this link to the View Item page is configured to select the applicable variation. |
|
ItemArray.Item .ListingEnhancement |
ListingEnhancementsCodeType | Conditionally,
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. 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. |
| ItemArray.Item.ListingType | ListingTypeCodeType | Conditionally |
The format of the listing the seller wants to use, such as Chinese auction or fixed price. Optional for eBay.com listings (defaults to Chinese auction) 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. Also known as Buy It Now Only on some sites (not to be confused with the BuyItNow option that is available for Chinese auctions). Sellers must meet certain feedback requirements and/or be ID Verified to use this format. See Minimum Feedback Requirements for Various Features in the Trading Web Services guide. Fixed-price listings are listed on eBay.com, and they are listed in the seller's eBay Store if the seller is a Store owner. Stores fixed price items will be treated as basic fixed-price items. Permitted durations of 30 days and GTC are now available for store and non-store subscribers (in addition to the existing durations of 3, 5, 7, and 10 days). Use the GetCategoryFeatures call to determine if a particular site has adopted this method. The release notes will also contain much of this information. • LeadGeneration (in/out) Lead Generation format (advertisement-style listing to solicit inquiries or offers, no bidding or fixed price, listed on eBay). • Live Deprecated as of version 601.
• Shopping (out) Reserved for internal or future use. You can ignore Shopping.com items in your results. • StoresFixedPrice (in/out) A fixed-price format for eBay Store sellers. Store Inventory listings appear after other listings in regular browse and search item lists on eBay. They have a lower Insertion Fee and longer listing durations. Only available to sellers who have an eBay Store. Store Inventory listings are listed on eBay.com, and they are also listed in the seller's eBay Store. Stores fixed price items will be treated as basic fixed-price items; please see the documentation for FixedPriceItem (that is, for the basic fixed-price item format). Use the GetCategoryFeatures call to determine if a particular site has adopted this method. The release notes will also contain much of this information. (Not all values in ListingTypeCodeType apply to this field.) See:
|
| ItemArray.Item.LocalListing | boolean | Conditionally | Indicates, when true, that an item is available locally. |
| ItemArray.Item.Location | string | Conditionally |
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. |
|
ItemArray.Item .MotorsGermanySearchable |
boolean | Conditionally |
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 eBay Web Services Guide for applicable categories, revise and relist rules, and additional information on featuring vehicles on the Mobile.de Site. Not applicable to Half.com. |
| ItemArray.Item.PictureDetails | PictureDetailsType | Conditionally |
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. |
|
ItemArray.Item.PictureDetails .GalleryType |
GalleryTypeCodeType | Conditionally |
Indicates whether listing images are included in the search results (in both Picture Gallery and List Views) and, if so, which image listing enhancements apply to them. Items that have pictures but do not have image listing enhancements display a generic photo image in search results. If the 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 is unable to 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: As of February 2008, the following sites offer free Gallery: US (site ID 0), Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), UK (site ID 3), CAFR (site ID 210), FR (site ID 71) and NL (site ID 146). Additionally, ES (site ID 186) and IT (site ID 101) offer free Gallery as of March 2008. 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) Listing is highlighted and included at the top of search results. • 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:
|
|
ItemArray.Item.PictureDetails .GalleryURL |
anyURI | Conditionally |
URL for a picture to be used as the Gallery thumbnail. 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: As of February 2008, the following sites offer free Gallery: US (site ID 0), Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CA (site ID 2), UK (site ID 3), CAFR (site ID 210), FR (site ID 71) and NL (site ID 146). Additionally, ES (site ID 186) and IT (site ID 101) offer free Gallery as of March 2008. 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. 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. For eBay Live Auctions, lots are listed in the gallery for free. 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. Max length: 1024. See:
|
| ItemArray.Item.Seller | UserType | Conditionally |
Container for information about this listing's seller. Not applicable to Half.com. Returned by GetItemsAwaitingFeedback if Buyer is making the request. |
|
ItemArray.Item.Seller .FeedbackPrivate |
boolean | Conditionally |
Indicates whether the user has chosen to make their feedback score and feedback details private (hidden from other users). Note that the percentage of positive feedback can still be returned, even if other feedback details are private. In GetSearchResults and GetCategoryListings, feedback information is only returned if IncludeFeedback = true in the request. Since a bidder's user info is anonymous, this tag will be returned only to that bidder, and to the seller of an item that the user is bidding on. |
|
ItemArray.Item.Seller .FeedbackScore |
int | Conditionally |
The aggregate feedback score for a user. A user's feedback score is the net positive feedback minus the net negative feedback left for the user. Feedback scores are a quantitative expression of the desirability of dealing with a user as a buyer or a seller in transactions. Each transaction can result in one feedback entry for a given user (the buyer can leave feedback for the seller, and the seller can leave feedback for the buyer.). That one feedback can be positive, negative, or neutral. The aggregated feedback counts for a particular user represent that user's overall feedback score (referred to as a "feedback rating" on the eBay site). If the user has chosen to make their feedback private and that user is not the user identified in the request's authentication token, FeedbackScore is not returned and FeedbackPrivate is returned with a value of true. In GetSearchResults and GetCategoryListings, feedback information is only returned if IncludeFeedback = true in the request. In GetMyeBayBuying and GetMyeBaySelling, feedback information (FeedbackScore and FeedbackRatingStar) is returned in BidList.ItemArray.Item.Seller. For GetMyeBayBuying, the feedback score of each seller with an item having received a bid from the buyer is returned. For GetMyeBaySelling, the feedback score of the seller is returned. GetMyeBayBuying and GetMyeBaySelling also return feedback information (FeedbackScore and FeedbackRatingStar) in BidList.ItemArray.Item.SellingStatus.HighBidder. GetMyeBayBuying returns feedback information on the high bidder of each item the buyer is bidding on. GetMyeBaySelling returns feedback information on the high bidder of each item the seller is selling. Since a bidder's user info is anonymous, the real feedback score will be returned only to that bidder, and to the seller of an item that the user is bidding on. For all other users, the value -99 is returned. |
|
ItemArray.Item.Seller .PositiveFeedbackPercent |
float | Conditionally | Percent of total feedback that is positive. For example, if the member has 50 feedbacks, where 49 are positive and 1 is neutral or negative, the positive feedback percent could be 98.0. The value uses a max precision of 4 and a scale of 1. If the user has feedback, this value can be returned regardless of whether the member has chosen to make their feedback private. Not returned if the user has no feedback. In GetSearchResults and GetCategoryListings, feedback information is only returned if IncludeFeedback = true in the request. |
| ItemArray.Item.SellingStatus | SellingStatusType | Conditionally |
Various details about the current status of the listing, such as the current number of bids and the current high bidder. Not applicable to Half.com. |
|
ItemArray.Item.SellingStatus .BidCount |
int | Conditionally | Number of bids placed so far against the item. Only applicable to competitive-bid item listings (Chinese auctions). |
|
ItemArray.Item.SellingStatus .ConvertedCurrentPrice |
AmountType (double) | Conditionally |
Converted value of the CurrentPrice in the currency of the site that returned this response. For active items, refresh the listing's data every 24 hours to pick up the current conversion rates. Only returned when the item's CurrentPrice on the listing site is in different currency than the currency of the host site for the user/application making the API call. ConvertedCurrentPrice is not returned for Classified listings (Classified listings are not available on all sites). In multi-variation listings, this value matches the lowest-priced variation that is still available for sale. |
|
ItemArray.Item.SellingStatus .CurrentPrice |
AmountType (double) | Conditionally |
For competitive-bid item listings (Chinese auctions), current minimum asking price (start price) or the current highest bid for the item if bids have been placed. Shows minimum bid if no bids have been placed on the item. For Basic Fixed-Price (FixedPriceItem), Store Inventory (StoresFixedPrice), or Ad type (AdType) listings this returns the original price specified when the item was listed/re-listed or the revised price if the item was revised using the ReviseItem call. In multi-variation listings, this value matches the lowest-priced variation that is still available for sale. |
| ItemArray.Item.Site | SiteCodeType | Conditionally |
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 (e.g., GetCategoryListings), 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, 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:
|
| ItemArray.Item.SubTitle | string | Conditionally |
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:
|
| ItemArray.Item.Title | string | Conditionally |
Name of the item as it appears in the listing or search results. Required for most items. Optional if you list in Books, Music, Movies, or Video Games categories and you use Pre-filled Item Information (as the title can be pre-filled based on the catalog product title). That is, optional if you specify Item.ExternalProductID or Item.ProductListingDetails. You cannot use HTML or JavaScript in the Title. (HTML characters will be interpreted literally as plain text.) For AddItem, not applicable to Half.com. For GetOrders, not returned from eBay.com, but a title from the Half.com catalog is returned from Half.com instead. You can add or change the value of this tag only if an item has no bids (or no items have sold) and the listing does not end for 12 hours. In GetItemRecommendations, more keywords in the title usually results in more relevant recommendations. Max length: 55. |
| ItemsPerPage | int | Always | Indicates the maximum number of item listings that will be returned per call. |
| PageNumber | int | Always | Indicates the page of data returned in the current call. |
| PaginationResult | PaginationResultType | Always | Indicates the results of the pagination, including the total number of pages of data there are to be returned and the total number of items there are to be returned. |
|
PaginationResult .TotalNumberOfEntries |
int | Always | Indicates the total number of entries that could be returned by repeated requests. For GetOrders, not applicable to eBay.com (for GetOrders, applicable to Half.com). Returned with a value of 0 if no entries are available. |
|
PaginationResult .TotalNumberOfPages |
int | Always | Indicates the total number of pages of data that could be returned by repeated requests. For GetOrders, not applicable to eBay.com (for GetOrders, applicable to Half.com). Returned with a value of 0 if no pages are available. |
| RelatedSearchKeywordArray | RelatedSearchKeywordArrayType | Conditionally | Container for keywords related to the category ID in the request. Can be returned if the request specified more than zero in the MaxRelatedSearchKeywords field. |
|
RelatedSearchKeywordArray .Keyword |
string | Conditionally,
repeatable: [0..*] |
Related keyword. |
| SubCategories | CategoryArrayType | Conditionally | Collection of the sub-categories that are child to the category indicated in Category. Data for each sub-category is conveyed in a CategoryType object. |
| SubCategories.Category | CategoryType | Always,
repeatable: [1..*] |
Contains details about one category. For GetCategories, this node is not returned when no detail level is specified. |
|
SubCategories.Category .CategoryID |
string | Always |
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. |
|
SubCategories.Category .CategoryName |
string | Always |
Display name of the category as it would appear on the eBay Web site. In GetItem, this is a fully qualified category name (e.g., Collectibles:Decorative Collectibles:Hummel, Goebel). In GetItem, always returned for eBay.com listings. Not returned in PrimaryCategory for Half.com listings. Max length: 30. |
| Input Output Samples Change History Top Errors for GetCategoryListings |
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 GetCategoryListings |
An inline sample will be added in a future release. Please refer to the Samples section of the eBay Web Services Guide chapter for GetCategoryListings.
| Input Output Detail Controls Samples Top Errors for GetCategoryListings |
| Version | Description |
|---|---|
| 581 2008-09-03 |
|
| 573 2008-07-09 |
|
| 561 2008-04-16 |
|
| 553 2008-02-20 |
|
| 537 2007-10-31 |
|
| 527 2007-08-22 |
|
| 521 2007-07-11 |
|
| 505 2007-03-21 |
|
| 501 2007-02-21 |
|
| 499 2007-02-07 |
|
| 491 2006-12-13 |
|
| 483 2006-10-18 |
|
| 481 2006-10-04 |
|
| 471 2006-7-26 |
|
| 469 2006-7-12 |
|
| 453 2006-03-22 |
|
| 451 2006-03-08 |
|
| 449 2006-02-22 |
|
| 439 2005-12-14 |
|
| 439 2005-12-14 |
|
| 433 2005-11-02 |
|
| 413 2005-06-15 |
|
This document was generated with a customized version of the apireferencedocs tool.
© 2005–2009 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.