FindProducts - Call Reference - eBay Shopping Web Services

FindProducts

FindProducts searches for stock catalog information for products, such as a particular digital camera model or a particular book. Some sellers include this stock information in their listings, to complement their own listing description. For a list of the kinds of products you can search for, see Product Domains for eBay Sites

Note: A product is not the same as an item. A product is essentially a stock description from a catalog. A item is something that a seller has listed.

For information about specifying affiliate parameters, see Affiliate URL Parameters and HTTP Header Values.

See the Input and Output sections below for a complete list of fields in this call.

This call is designed to be useful to applications that support shopping comparisons or basic supply and demand data. It returns basic product information, such as the title, stock photo (if any), and Item Specifics. Item Specifics are well-known aspects of products in the same domain or category. For example, a book's item specifics might include a field like Publication Year=2007, and a field like Binding=Hardcover. But a ticket's item specifics would be different from a book's, with fields like EventType=Concerts and Venue=The Fillmore.

To use this call, you typically start by passing in keywords (such as a book title) in QueryKeywords, and eBay finds products with matching words in the product title, description, and/or Item Specifics. This is similar (although not identical to) using the Express Product Search page on the eBay Web site:

Harry Potter Children's Books Product Search
http://product-search.ebay.com/harry-potter_Childrens-Books_
W0QQoptprodpageZtrueQQpfidZ1399QQpfmodeZ2QQpopgnZQQpopnmZChildrenQ27sQ20Books
QQpoqryZharryQ20potterQQpostaZQQpovcsZ1389QQsofocusZ

To get more information about one of the products (such as the eBay listings that use the product's stock information), take the product's ID from the response and pass it back into FindProducts in ProductID.

For each product of interest, you can retrieve up 200 items on eBay (if any) that were listed with the product's stock information. (This call does not find items that match the product's title; it only finds items for which the seller actually included the product's stock information in their listing.) This is similar to retrieving a product and its Listings page on the eBay Web site. (To find more listings (if any), use FindItemsAdvanced.)

Harry Potter Book Product and Listings
http://search.product.ebay.com/Harry-Potter-and-the-Deathly-Hallows_
ISBN-10_0545010225_ISBN-13_9780545010221_W0QQfromZR31QQfvcsZ1389QQsoprZ59049480QQupvrZ2

A product can have several kinds of product IDs. In most cases, you use the product's reference ID for searching. This is an ID that doesn't usually change. However, in media categories (Books, Music, DVDs & Movies, and Video Games) only, you can use an industry-standard ISBN, EAN, or UPC value instead of the reference ID.

Note: As catalog queries can take longer than item queries, FindProducts can be slower than FindItemsAdvanced. Also, due to the way product data is cached, you may get a faster response when you run the same query a second time.

FindProducts supports affiliate tracking for members of the eBay Affiliates Program.

Best Practices

FindProducts has been optimized for response size, speed and usability. So, it returns the most commonly used fields by default. Use the IncludeSelector field to get more data—but please note that getting more data can result in longer response times.

If you're showing an item to a potential buyer and you know where that buyer is located, it may be helpful to check where the seller is willing to ship the item (ShipToLocations). Some sellers will ship worldwide, and others prefer to ship to certain countries or regions only.

More Tips

If you discover other useful practices, feel free to add them in the User-Contributed Notes at the bottom of this page.

If you're looking for more tips, try searching the Knowledge Base and Developer Forums.

Related calls:

FindItemsAdvanced - Searches for items based on many possible input fields. Detailed information is returned about items.

FindProducts Input

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).

Argument	Type	Reqd?	Meaning
Standard Input Fields [Jump to call-specific fields]
MessageID	string	Optional	If you pass a value in MessageID in a request, we'll return the same value in CorrelationID in the response. If you're making a lot of calls, you can use this for tracking that a response is returned for every request and to match particular responses to particular requests. (In this case, specify a different value for each request.) You can specify any value that is useful to you.
Call-specific Input Fields
AvailableItemsOnly	boolean	Optional	If true, only retrieve data for products that have been used to pre-fill active listings on the specified eBay site. If false, retrieve all products that match the query. This is useful when you use QueryKeywords and you only want to find products that have associated items (that is, where ItemArray would not beempty). This does not retrieve ItemArray; this only controls which products are returned (or counted). To retrieve ItemArray, pass Items in IncludeSelector. Default: false.
CategoryID	string	Conditional	Include a Category ID number in your request to restrict your query to a specific category. Max length: 10.
DomainName	string (repeatable)	Optional	A domain to search in. This is like searching a section of a catalog. If not specified, the product search is conducted across all domains. DomainName is an unbounded field. If you are using a URL, and you want to specify multiple values, use an index value (not a comma). For example, to specify DomainName=Textbooks,Education, specify DomainName(0)=Textbooks,%20Education. To determine valid domain names, first use this call with QueryKeywords. Domain names are returned for each product (and summarized in the domain histogram, if you specify DomainHistogram in IncludeSelector). A domain is a named grouping of categories whose items share common product characteristics. For example, all bound books have a binding or format (e.g., Hardcover), but audiobooks don't. So audiobooks would have their own domain. To limit your search to audiobooks, you would specify Audiobooks as the domain. Only useful when QueryKeywords is specified. If you use this with ProductID, AND logic is applied. In this case, if you specify an ID that doesn't match the domain (as eBay has defined it), no matching product will be found. Therefore, we recommend that you only use DomainName with QueryKeywords.
IncludeSelector	string	Optional	Defines standard subsets of fields to return within the response. If you don't specify this field, the call returns a default set of fields, focusing on product details only (see the "Detail Controls" link below). If you specify this field, the additional fields you retrieve can affect the call's response time (performance). Applicable values: • Details Include all available item fields in the response. Only applicable when you are searching by ProductID. Not applicable with QueryKeywords. • DomainHistogram Include the DomainHistogram in the response. The histogram lists the number of matching products found and the domains in which they were found. (A domain is like a high-level category.) When many matching products are found, you may see significantly slower response times when you include the histogram. • Items Include a brief set of item fields in the response. Only applicable when you are searching by ProductID. Not applicable with QueryKeywords. Use a comma to specify multiple values. (In this case, the results are cumulative.) See "FindProducts Samples" for an example of how to use this field. See "Detail Controls" for a complete list of fields that can be returned for each selector.
MaxEntries	int	Optional	Specifies the maximum number of products to return per page in a single call. This is mostly only useful with QueryKeywords. (When you use ProductID, eBay usually only returns one product, and up to 200 items for that product.) Min: 1. Max: 20. Default: 1.
PageNumber	int	Optional	Specifies which page of data to return in the current call. 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). Min: 1. Max: 2000. Default: 1.
ProductID	ProductIDType (string)	Conditional	Use this to retrieve product details for one specific product. Specify the ID as a string, and use the type attribute to indicate the nature of the ID you are specifying. The request requires either QueryKeywords or ProductID, but these fields cannot be used together. Max length: 4000.
ProductID [ attribute type ]	ProductIDCodeType	Conditional	The nature of identifier being used. For FindHalfProducts, FindProducts, FindItemsAdvanced, and FindReviewsAndGuides, only Reference, ISBN, UPC, and EAN are supported. Required when ProductID is specified. For a list of possible enumeration values, see ProductIDCodeType.
ProductSort	ProductSortCodeType	Optional	Sorts the list of products returned. This is mostly only useful with QueryKeywords. (When you use ProductID, eBay usually only returns one product.) Also see SortOrder. If ProductSort and SortOrder are not specified, products are sorted by popularity in descending order. Default: Popularity. Applicable values: • CustomCode (in) Reserved for values that are not available in the version of the schema you are using. If eBay adds a new value to this code type as of a newer version, we return CustomCode instead when you specify a lower request version. • ItemCount (in) Sort by the number of active items listed with this product. • Popularity (in) Sort by product popularity (as determined by eBay). (This is the default sort order.) • Rating (in) Sort by average rating. • ReviewCount (in) Sort by the number of reviews on eBay. • Title (in) Sort by the product title.
QueryKeywords	string	Conditional	One or more keywords to search for. When you use a keyword search, eBay searches the product catalogs for matching words in the product title, description, and/or Item Specifics, and it returns a list of matching products, with no items. To retrieve items, use ProductID instead. (If you don't already have a product ID, you can get product IDs from the response after conducting a keyword search.) If specified, you must pass in at least 3 alphanumeric characters. The words "and" and "or" are treated like any other word. Only use "and", "or", or "the" if you are searching for products containing these words. To use AND or OR logic, use eBay's standard search string modifiers. Wildcards (+, -, or ) are also supported. Be careful when using spaces before or after modifiers and wildcards. Some keyword queries can result in response times of 30 seconds or longer. If more than 2000 matches are found, the call fails with an error. If this kind of error occurs, refine the search by passing in more keywords and/or by using DomainName to restrict the search to certain domains (such as DVDs). If you are searching for a particular book, DVD, CD, or video game and you already know its ISBN or EAN (for a book) or UPC, consider using ProductID instead to retrieve more precise results. The request requires either QueryKeywords or ProductID, but these fields cannot be used together. Max length:* 350.
SortOrder	SortOrderCodeType	Optional	Sorts search results in ascending or descending order. Only applicable with ProductSort. If you specify ProductSort without SortOrder, the order defaults to Descending for all criteria except Title (which defaults to Ascending). Default: Descending. Applicable values: • Ascending (in) Sorts results in ascending (low to high) order. • CustomCode (in) Placeholder value. See token. • Descending (in) Sorts results in descending (high to low) order.

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).

<?xml version="1.0" encoding="utf-8"?>
<FindProductsResponse 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 ... -->
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
  <!-- Call-specific Output Fields -->
  <ApproximatePages> int </ApproximatePages>
  <DomainHistogram> DomainHistogramType 
    <Domain> HistogramEntryType 
      <Count> int </Count>
      <Name> string </Name>
    </Domain>
    <!-- ... more Domain nodes here ... -->
  </DomainHistogram>
  <ItemArray> SimpleItemArrayType 
    <Item> SimpleItemType 
      <BestOfferEnabled> boolean </BestOfferEnabled>
      <BidCount> int </BidCount>
      <BuyItNowAvailable> boolean </BuyItNowAvailable>
      <BuyItNowPrice> AmountType (double) </BuyItNowPrice>
      <ConvertedBuyItNowPrice> AmountType (double) </ConvertedBuyItNowPrice>
      <ConvertedCurrentPrice> AmountType (double) </ConvertedCurrentPrice>
      <Country> CountryCodeType </Country>
      <CurrentPrice> AmountType (double) </CurrentPrice>
      <EndTime> dateTime </EndTime>
      <GalleryURL> anyURI </GalleryURL>
      <ItemID> string </ItemID>
      <ListingStatus> ListingStatusCodeType </ListingStatus>
      <ListingType> ListingTypeCodeType </ListingType>
      <PaymentMethods> BuyerPaymentMethodCodeType </PaymentMethods>
      <!-- ... more PaymentMethods nodes here ... -->
      <PostalCode> string </PostalCode>
      <PrimaryCategoryID> string </PrimaryCategoryID>
      <PrimaryCategoryName> string </PrimaryCategoryName>
      <SecondaryCategoryID> string </SecondaryCategoryID>
      <SecondaryCategoryName> string </SecondaryCategoryName>
      <ShippingCostSummary> ShippingCostSummaryType 
        <ShippingServiceCost> AmountType (double) </ShippingServiceCost>
        <ShippingType> ShippingTypeCodeType </ShippingType>
      </ShippingCostSummary>
      <ShipToLocations> string </ShipToLocations>
      <!-- ... more ShipToLocations nodes here ... -->
      <Site> SiteCodeType </Site>
      <StartTime> dateTime </StartTime>
      <Subtitle> string </Subtitle>
      <TimeLeft> duration </TimeLeft>
      <Title> string </Title>
      <ViewItemURLForNaturalSearch> anyURI </ViewItemURLForNaturalSearch>
    </Item>
    <!-- ... more Item nodes here ... -->
  </ItemArray>
  <MoreResults> boolean </MoreResults>
  <PageNumber> int </PageNumber>
  <Product> CatalogProductType 
    <DetailsURL> anyURI </DetailsURL>
    <DisplayStockPhotos> boolean </DisplayStockPhotos>
    <DomainName> string </DomainName>
    <ItemCount> int </ItemCount>
    <ItemSpecifics> NameValueListArrayType 
      <NameValueList> NameValueListType 
        <Name> string </Name>
        <Value> string </Value>
        <!-- ... more Value nodes here ... -->
      </NameValueList>
      <!-- ... more NameValueList nodes here ... -->
    </ItemSpecifics>
    <ProductID> ProductIDType (string) </ProductID>
    <!-- ... more ProductID nodes here ... -->
    <ProductState> ProductStateCodeType </ProductState>
    <ReviewCount> int </ReviewCount>
    <StockPhotoURL> anyURI </StockPhotoURL>
    <Title> string </Title>
  </Product>
  <!-- ... more Product nodes here ... -->
  <TotalProducts> int </TotalProducts>
</FindProductsResponse>

Return Value	Type	Returned?	Meaning
Standard Output Fields [Jump to call-specific fields]
Ack	AckCodeType	Always	Indicates whether the call was successfully processed by eBay. 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 particular 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	If you pass a value in MessageID 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. Only returned if MessageID was used.
Errors	ErrorType (repeatable)	Conditionally	A list of application-level errors or warnings (if any) that were raised when eBay processed the request. Application-level errors occur due to problems with business-level data on the client side or on the eBay server side. For example, an error would occur if the request contains an invalid combination of fields, or it is missing a required field, or the value of the field is not recognized. An error could also occur if eBay encountered a problem in our internal business logic while processing the request. Only returned if there were warnings or errors.
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. See Errors by Number.
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 Errors by Number.
Errors.ErrorParameters	ErrorParameterType (repeatable)	Conditionally	Some warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error. You can usually predict where these will occur by looking at the "replaceable_value" indicators in our Errors by Number page. See Errors by Number.
Errors.ErrorParameters [ attribute ParamID ]	string	Conditionally	The index of the parameter in the error.
Errors.ErrorParameters.Value	string	Conditionally	The value of the variable.
Errors.LongMessage	string	Conditionally	A more detailed description of the condition that raised the error. See Errors by Number.
Errors.SeverityCode	SeverityCodeType	Conditionally	Indicates whether the error caused the request to fail. If the request fails and the source of the problem is within the application (such as a missing required element), please change the application before you retry the request. If the problem is due to end-user input data, please alert the end-user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, you can attempt to re-send the request to eBay. If the source of the problem is on eBay's side, you 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. When a warning occurs, the error is returned in addition to the business data. In this case, you do not need to retry the request (as the original request was successful). However, depending on the cause or nature of the warning, you might need to contact either the end user or eBay to effect a long term solution to the problem to prevent it from reoccurring in the future. Applicable values: • CustomCode (out) Reserved for internal or future use • Error (out) The request that triggered the error was not processed successfully. When a serious application-level error occurs, the error is returned instead of the business data. • Warning (out) The request was processed successfully, but something occurred that may affect your application or the user. For example, eBay may have changed a value the user sent in. In this case, eBay returns a normal, successful response and also returns the warning. See: Errors by Number Requirements for Error Handling for more information (in the eBay Trading Web Services guide)
Errors.ShortMessage	string	Conditionally	A brief description of the condition that raised the error. See Errors by Number.
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 the "dateTime" type for information about this time format and converting to and from the GMT time zone.
Version	string	Always	The release version that eBay used to process the request. Note: This is usually the latest release version, as specified in the release notes. (eBay releases the API to international sites about a week after we release it to the US site.) If a field in the response returns the token "CustomCode", it usually means that the field is a code type (a token or enumeration), and that in your request URL (or HTTP header) you specified a version that is older than the version in which the token was added to the call. See eBay Versioning Strategy.
Call-specific Output Fields
ApproximatePages	int	Always	The total number of pages that can be returned, given the same query and filters in the request. As FindProducts only returns up to 2000 products, the maximum possible value is theoretically 2000 (if you were to set MaxEntries to 1 in the request). Min: 1. Max: 2000. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
DomainHistogram	DomainHistogramType	Conditionally	A histogram that lists the number of matching products found and the domains in which they were found. A domain describes a set of categories that share certain common characteristics (as determined by eBay). Each domain has its own name and ID. Only returned when you specify DomainHistogram in IncludeSelector. IncludeSelector: DomainHistogram.
DomainHistogram.Domain	HistogramEntryType (repeatable)	Conditionally	Each histogram entry shows how many matching products were found in each matching domain. A domain is like a high-level category, or a group of categories whose items share the same basic product characteristics. IncludeSelector: DomainHistogram.
DomainHistogram.Domain.Count	int	Conditionally	This is the number of products found in the domain. If a product is mapped to more than one domain, it is counted separately for each domain. (For example, if the same product name appears in both Children's Books and Fiction Books, the count for both of these domains will include that product.) This means you cannot sum the product counts to determine the total number of matching products across all domains. The histogram is only intended to show the number of matching products in each individual domain. IncludeSelector: DomainHistogram.
DomainHistogram.Domain.Name	string	Conditionally	This is the domain name. A product can be mapped to more than one domain. This means that even if a name appears in this histogram and the Count is greater than 1, you won't necessarily see the same name returned for each returned product (in the Product node of the response). That is, Product.DomainName only returns the most applicable domain name (as determined by eBay). IncludeSelector: DomainHistogram.
ItemArray	SimpleItemArrayType	Conditionally	A list of active items that were listed with the requested product. Only returned when you specify Items in IncludeSelector, and the product has matching items that are currently active on eBay. IncludeSelector: Details, Items.
ItemArray.Item	SimpleItemType (repeatable)	Conditionally	Contains data for an item listing. IncludeSelector: Details, Items.
ItemArray.Item .BestOfferEnabled	boolean	Conditionally	Whether the seller will accept a best offer for this item. This feature enables a buyer to make a lower-priced binding offer on a fixed price item. Buyers can't see how many offers have been made (only the seller can see this information). To make a best offer on a listing, use the eBay Web site. IncludeSelector: Details. See: (eBay Help) Making a Best Offer (for Buyers) (eBay DE Hilfe) Preis vorschlagen
ItemArray.Item.BidCount	int	Conditionally	The number of bids that have been placed on the item. On most sites, once a Chinese auction has bids, the listing is no longer eligible for Buy It Now. (This is not necessarily true for Dutch auctions. See Item.BuyItNowAvailable for Dutch auctions.) IncludeSelector: Details, Items.
ItemArray.Item .BuyItNowAvailable	boolean	Conditionally	For Dutch auctions (not Chinese auctions) this indicates whether there is a Buy It Now option. (On some sites, the Buy It Now option remains available for Dutch auctions even after there are bids.) Applicable to the Germany site (site ID 77) only. IncludeSelector: Details, Items.
ItemArray.Item.BuyItNowPrice	AmountType (double)	Conditionally	The Buy It Now Price of the item (if any), in the currency of the site on which the item was listed. For Chinese auctions (Quantity=1, competitive bidding online auctions), Buy It Now lets a user purchase the item at a fixed price and end the auction immediately. On most sites, after a Chinese auction has bids, the listing is no longer eligible for Buy It Now. However, calls can still return the Buy It Now Price that the seller set for the listing. Use the Item.BidCount field to determine whether an auction with Buy It Now has bids or not. Some eBay sites also support Buy It Now for Dutch auctions (multi-quantity, competitive bidding), where you can buy multiple items from the same listing at a fixed price, instead of bidding. On some sites, the Buy It Now option remains available for Dutch auctions even after there are bids. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Only returned if an item was listed with Buy It Now. IncludeSelector: Details. See: (GetSingleItem) Item.ListingType Item.BuyItNowAvailable Item.ConvertedBuyItNowPrice Item.ConvertedCurrentPrice (eBay Help) Buying with Buy It Now (eBay DE Hilfe) Kaufen mit Sofort-Kaufen
ItemArray.Item .ConvertedBuyItNowPrice	AmountType (double)	Conditionally	The listing's Buy It Now Price (if any), converted into the currency of the site to which you sent this request. Price fields are returned as doubles, not necessarily in the traditional monetary format of the site's country. For example, a US Dollar value might be returned as 3.880001 instead of 3.88. For Chinese auctions (Quantity=1, competitive bidding online auctions), Buy It Now lets a user purchase the item at a fixed price and end the auction immediately. On most sites, after a Chinese auction has bids, the listing is no longer eligible for Buy It Now. However, calls like FindItems still return the Buy It Now Price that the seller set for the listing. Use the Item.BidCount field to determine whether an auction with Buy It Now has bids or not (and therefore whether it is still eligible to be purchased with Buy It Now). Some eBay sites also support Buy It Now for Dutch auctions (multi-quantity, competitive bidding), where you can buy multiple items from the same listing at a fixed price, instead of bidding. On some sites, the Buy It Now option remains available for Dutch auctions even after there are bids. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Only returned if an item was listed with Buy It Now. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). IncludeSelector: Details, Items. See: (GetSingleItem) Item.ListingType Item.BuyItNowAvailable Item.BuyItNowPrice Item.ConvertedCurrentPrice (eBay Help) Buying with Buy It Now (eBay DE Hilfe) Kaufen mit Sofort-Kaufen
ItemArray.Item .ConvertedCurrentPrice	AmountType (double)	Conditionally	The listing's current price, converted to the currency of the site specified in the request. If the item is a multi-quantity listing, this is the price of one item. Price fields are returned as doubles, not necessarily in the usual monetary amount format of the site. For example, a US Dollar value might be returned as 3.879938 instead of 3.88. For competitive-bidding listings (Chinese and Dutch auctions), this is the current minimum bid price (if the listing has no bids) or the current high bid (if the listing has bids). (Compare to BuyItNowPrice). For Basic Fixed-Price (FixedPriceItem), Store Inventory (StoresFixedPrice), and Ad format (AdType) listings, this is the current fixed price. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). IncludeSelector: Details, Items.
ItemArray.Item.Country	CountryCodeType	Conditionally	Two-letter ISO 3166 country code to indicate the country where the item is located. Applicable values: See Country. IncludeSelector: Details.
ItemArray.Item.CurrentPrice	AmountType (double)	Conditionally	The current price of the item, in the currency of the site on which the item was listed. That is, CurrentPrice is in the original listing currency. If the item is a multi-quantity listing, this is the price of one item. For competitive-bidding listings (Chinese and Dutch auctions), this is the current minimum bid price (if the listing has no bids) or the current high bid (if the listing has bids). (Compare to BuyItNowPrice). For Basic Fixed-Price (FixedPriceItem), Store Inventory (StoresFixedPrice), and Ad format (AdType) listings, this is the current fixed price. IncludeSelector: Details.
ItemArray.Item.EndTime	dateTime	Conditionally	Time stamp (in GMT) of when the listing is scheduled to end, or time stamp of the actual end time (if the item ended). In FindItemsAdvanced and FindItems, 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. IncludeSelector: Details, Items.
ItemArray.Item.GalleryURL	anyURI	Conditionally	URL for a picture used as the Gallery thumbnail, if any. The image uses one of the following graphics formats: JPEG, BMP, TIF, or GIF. Only returned if the seller chose to show a gallery image. IncludeSelector: Details, Items.
ItemArray.Item.ItemID	string	Conditionally	The ID that uniquely identifies the item listing. eBay generates this ID when an item is listed. This ID is unique across all eBay sites. Max length: 19 (Note: The eBay database specifies 38. Currently, Item IDs are usually 9 to 12 digits). IncludeSelector: Details, Items.
ItemArray.Item.ListingStatus	ListingStatusCodeType	Conditionally	Specifies a listing's status in eBay's processing workflow. If an item's EndTime is in the past, but no details about the buyer or high bidder are shown (and the user is not anonymous), use this listing status information to determine whether eBay has finished processing the listing. Applicable values: • Active (out) The listing is still live, or it has recently ended but eBay has not completed processing the listing (e.g., we're still determining the high bidder). A multi-item listing is considered active until all items have winning bids or purchases or the listing's end time has passed. (That is, if the listing has a Quantity of 10, the sale of 1 of those items doesn't end the listing.) If the listing has ended but this Active status is returned, please allow several minutes for eBay to finish processing the listing. • Completed (out) The listing has ended and eBay has completed processing of the sale (if any), such as determining the high bidder. You can think of Completed and Ended as essentially equivalent. (The difference is only meaningful to the seller of the item, as Completed indicates whether eBay has finished calculating certain selling fees.) • CustomCode (out) Placeholder value. See token. • Ended (out) The listing has ended and eBay has completed processing of the sale (if any), such as determining the high bidder. IncludeSelector: Details, Items.
ItemArray.Item.ListingType	ListingTypeCodeType	Conditionally	The format of the listing, such as online auction, fixed price, or advertisement format. Applicable values: • AdType (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 (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 (out) Placeholder value. See token. • Dutch (out) Multiple-quantity online auction format. A Dutch auction has a Quantity greater than 1. Buyers engage in competitive bidding. Some sites also offer Buy It Now for Dutch auctions. 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. • Express (out) For Germany only: eBay Express-only format (item is listed only on eBay Express Germany, not on eBay). • FixedPriceItem (out) A basic fixed-price listing with a Quantity of 1 or more. Allows no auction-style bidding. Also known as Buy It Now Only on some sites (not to be confused with the BuyItNow option that is available for Chinese auctions). Fixed-price listings appear on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • LeadGeneration (out) Lead Generation format (advertisement-style listing to solicit inquiries or offers, no bidding or fixed price, listed on eBay). • Live (out) Live auction, on-site auction that can include non-eBay bidders. Live auctions are listed on the eBay Live Auctions site, in live auction categories. They can also appear on eBay if the seller lists the lot in a secondary category that is an eBay category. • PersonalOffer (out) Second chance offer made to a non-winning bidder on an ended listing. A seller can make an offer to a non-winning bidder when either the winning bidder has failed to pay for an item or the seller has a duplicate of the item. Second-chance offer items are on eBay, but they do not appear when browsing or searching listings. You need to already know the item ID in order to retrieve a second-chance offer. • StoresFixedPrice (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 specified by 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. • Unknown (out) Unknown auction type. (This is not normally used.) (Not all values in ListingTypeCodeType apply to this field.) IncludeSelector: Details, Items.
ItemArray.Item.PaymentMethods	BuyerPaymentMethodCodeType (repeatable)	Conditionally	Identifies the payment method (such as PayPal) the seller will accept when the buyer pays for the item. Note: If the seller only accepts PayPal, the buyer can still pay with a credit card. PayPal supports major credit cards. Payment methods are not applicable to eBay Real Estate advertisement listings, or other Classified Ad format listings. Applicable values: See PaymentMethods. IncludeSelector: Details.
ItemArray.Item.PostalCode	string	Conditionally	Postal code indicating the physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.) IncludeSelector: Details.
ItemArray.Item .PrimaryCategoryID	string	Conditionally	Numeric ID of the first (or only) category in which the item is listed. (Listings can appear in more than one category.) Note: Currently, GetSingleItem does not return a listing's secondary category, if any. IncludeSelector: Details, Items.
ItemArray.Item .PrimaryCategoryName	string	Conditionally	Display name of the first (or only) category in which the item is listed. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks). IncludeSelector: Details, Items.
ItemArray.Item .SecondaryCategoryID	string	Conditionally	ID of the second category in which the item is listed. IncludeSelector: Details.
ItemArray.Item .SecondaryCategoryName	string	Conditionally	Name of the second category in which the item is listed. IncludeSelector: Details.
ItemArray.Item .ShippingCostSummary	ShippingCostSummaryType	Conditionally	Contains basic shipping-related costs for the item. If Item.Quantity is greater than 1, this is the shipping cost for one item. If the seller offers a choice of more than one shipping service (such as UPS Ground and USPS Media mail), this is the cost of the "first" shipping option (usually the lowest cost option). If a listing has shipping costs, use GetShippingCosts if you want to get more details about the services and costs that the seller is offering. IncludeSelector: Details, Items. See GetShippingCosts.
ItemArray.Item .ShippingCostSummary .ShippingServiceCost	AmountType (double)	Conditionally	The basic shipping cost of the item. If multiple items were purchased, this includes the ShippingServiceAdditionalCost. IncludeSelector: Details, Items.
ItemArray.Item .ShippingCostSummary .ShippingType	ShippingTypeCodeType	Conditionally	How the seller stated that cost of shipping is to be determined, such as flat rate or calculated or free. In GetSingleItem, this is always returned when ShippingCostSummary is returned. Applicable values: • Calculated (out) The calculated shipping model: the posted cost of shipping is based on the seller-offered and buyer-selected shipping service, where the shipping costs are calculated by eBay and the shipping carrier based on the buyer's address, and any packaging/handling costs established by the seller are automatically rolled into the total. • CalculatedDomesticFlatInternational (out) The seller specified one or more calculated domestic shipping services and one or more flat international shipping services. • CustomCode (out) Placeholder value. See token. • Flat (out) The flat rate 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 (out) The seller specified one or more flat domestic shipping services and one or more calculated international shipping services. • Free (out) Free is used when the seller is declaring that shipping is free for the buyer. Since Free cannot be selected via API, the seller has two options for signifying that shipping is free when listing an item: - omit shipping details, mention in the item description that shipping is free, and set ShippingTermsInDescription to true - select an arbitrary shipping service and set its shipping cost to 0, mention in the item description that shipping is free, and set ShippingTermsInDescription to true The latter is a better way to communicate "free shipping" because eBay picks up the "0" cost and can more accurately identify shipping costs in search results. • Freight (out) The freight shipping model: the cost of shipping is determined by a third party, FreightQuote.com, based on the item location (zip code). Currently, Freight can only be specified on input via eBay Web site, not via API. • NotSpecified (out) The seller did not specify the shipping type. IncludeSelector: Details, Items.
ItemArray.Item.ShipToLocations	string (repeatable)	Conditionally	An international location or region to which the seller is willing to ship this item. Returned only for items that have ShipToLocations specified. Applicable values: • Americas (North, South, or Latin America) • Asia • Caribbean • Europe • EuropeanUnion • LatinAmerica • MiddleEast • NorthAmerica • Oceania (Pacific region other than Asia) • SouthAmerica • WillNotShip (No shipping, buyer must pick up the item) • Worldwide (Seller will ship worldwide) • 2-letter country identifier (See CountryCodeType for values) IncludeSelector: Details. See CountryCodeType.
ItemArray.Item.Site	SiteCodeType	Conditionally	The name of the eBay site on which the item was originally listed. For example, if the item is listed on the eBay US site, the value would be US. If it's listed on the eBay Germany site, the value would be Germany. The listing's original site can affect the values of converted (localized) prices (when your request specifies a site that is different from the listing's site). Applicable values: See Site. IncludeSelector: Details.
ItemArray.Item.StartTime	dateTime	Conditionally	Time stamp (in GMT) that eBay recorded as the moment that the listing was made available. The start time returned by a search call may vary from the value returned by GetSingleItem. IncludeSelector: Details.
ItemArray.Item.Subtitle	string	Conditionally	Subtitle of the item. Only returned if the seller included a subtitle for the listing. For US eBay Motors passenger vehicle, motorcycle, and "other vehicle" categories or listings in CA eBay Motors passenger vehicle and motorcycle categories, see the ItemSpecifics node for the subtitle instead. IncludeSelector: Details.
ItemArray.Item.TimeLeft	duration	Conditionally	Time left before the listing ends. The duration is represented in the ISO 8601 duration format (PnYnMnDTnHnMnS). For ended listings, the time left is PT0S (zero seconds). IncludeSelector: Details, Items.
ItemArray.Item.Title	string	Conditionally	Name of the item as it appears in the listing or in search and browse results. For US eBay Motors cars, trucks, and motorcycles, this value shows the vehicle Make and Model instead of the seller's own title. (For the seller's title, look for Subtitle in Item.ItemSpecifics.NameValueList.Name in GetSingleItem, and then use the corresponding value in Item.ItemSpecifics.NameValueList.Value.) IncludeSelector: Details, Items.
ItemArray.Item .ViewItemURLForNaturalSearch	anyURI	Conditionally	The URL to view this listing on eBay. 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. For example, this URL specifies the item title, and it is optimized for natural search: "_W0QQ" is like "?" (question mark), "QQ" is like "&" (ampersand), and "Z" is like "=" (equals sign). You shouldn't modify the query syntax in your application. For example, eBay won't recognize the URL if you change QQ to ?. In the Sandbox environment and on the Hong Kong site (site ID 201), the data returned in this field by FindItemsAdvanced is a standard ViewItem URL, rather than the ViewItem URL for natural search that generally is returned in the Production environment. IncludeSelector: Details, Items.
MoreResults	boolean	Always	If true, more pages of results are available. That is, PageNumber is less than ApproximatePages. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
PageNumber	int	Always	The number of the page of data returned. If many products are found and multiple pages of results are available, use this in combination with ApproximatePages and MoreResults to decide which page to retrieve next. As FindProducts only returns up to 2000 products, the maximum possible value is theoretically 2000 (if you were to set MaxEntries to 1 in the request). Min: 1. Max: 2000. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product	CatalogProductType (repeatable)	Always	An eBay catalog product. This contains stock information about a particular DVD, camera, set of golf clubs, or other product. When you use QueryKeywords in the request, FindProducts returns a maximum of 20 products per page. When you use ProductID in the request, FindProducts usually only returns 1 product. (If more than one product matches the same ProductID, FindProducts will return all of those products. As of the time of this writing, we expect this to be a rare case.) IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.DetailsURL	anyURI	Conditionally	Fully qualified URL for 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 in product search results so that end users can view additional descriptive details about the product. This is usually always returned when Product is returned, but it may be safest to check for the existence of this field. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.DisplayStockPhotos	boolean	Conditionally	If true, your application can attempt to display stock photos that are returned. If false, your application should not attempt to display any stock photos that are returned. This recommendation is useful for catalog data related to products like coins, where stock photos are not necessarily applicable or available. An application with a graphical user interface can use this flag to determine when to hide customized stock photo widgets. Always returned when Product is returned. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.DomainName	string	Conditionally	The name of the domain in which the product was found. If the product is mapped to multiple domains, eBay returns the most applicable domain (as determined by eBay). Always returned when Product is returned. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.ItemCount	int	Conditionally	Total number of listings on the requested eBay site that use stock information from this catalog product. This value can be greater than the number of listings returned in ItemArray. To retrieve more listings, use FindItemsAdvanced. Only returned when you search by ProductID (and you pass Items or Details in IncludeSelector). Min: 0. IncludeSelector: Details, Items.
Product.ItemSpecifics	NameValueListArrayType	Conditionally	A list of name/value pairs that are included in the product's pre-filled Item Specifics. These indicate common aspects or characteristics of the product, such as Publisher (for a book). Also see ProductID for ISBN, UPC, or EAN values, if applicable. This is usually returned. (We are not aware of any cases in which this node is not be returned. However, it may be safest to check for the existence of this node.) IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.ItemSpecifics .NameValueList	NameValueListType (repeatable)	Conditionally	This list is an array of Item Specifics, which are category-specific fields that the seller added to describe the listing. The names of these fields are different for items in different categories, so they're returned in a generic name/value structure. For example, Item Specifics for a car might include a field like Make=Toyota (where Make is returned in Name, and Toyota is returned in Value) and Model=Prius (where Model is returned in Name, and Prius is returned in Value). For FindProducts, this can also be an Item Specific that is defined for a product. That is, Item Specifics can be returned both for items and products in FindProducts. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.ItemSpecifics .NameValueList.Name	string	Conditionally	The name of the item specific. This field is always returned for each item specific that is returned (if any). However if the seller didn't select a value for the item specific, we suggest you don't show the name (to avoid confusing users). For the item condition, this usually includes the word "Condition" for eBay US, UK, Australia, and India listings; and "Artikelzustand" for eBay Germany, Austria, and Switzerland listings. The Name fields in return policy item specifics (if any) usually include the word "return", "refund", and/or "warranty" for eBay US, Canada, UK, Australia, and India listings; and "Rucknahme", "return", and/or "refund" for eBay Germany, Austria, and Switzerland listings. Note: Ignore item specifics with SIFFTAS in the name. These are for internal use by eBay and aren't meaningful to users. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.ItemSpecifics .NameValueList.Value	string (repeatable)	Conditionally	A value for the item specific. In GetSingleItem, this field is always returned for each item specific that is returned (if any). However, if the seller didn't select a value for the item specific, this field may return empty, or it may return a value like "-", "Not Selected", or "Unspecified" (or the equivalent in the language of the site). For the item condition, this usually includes the word "New" or "Used" for eBay US, UK, Australia, and India listings; and "Neu" or "Gebraucht" for eBay Germany, Austria, and Switzerland listings. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.ProductID	ProductIDType (string) (repeatable)	Conditionally	The eBay or external IDs associated with the product. Use the Reference value as input to search for the same product in the future, or use the ISBN, EAN, or UPC value (if returned). The ISBN, EAN, and UPC values can also be useful as keys if your application is comparing products across different sites. Always returned when Product is returned. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
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). As of mid-2008, 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. If your application currently uses the product for 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 searching, we recommend that you update your application to use a product that is not scheduled to be merged or deleted. • Update (out) The product 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 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 for searching, but it may contain fewer details than other products. If your application currently uses the product for searching, we recommend that you check to make sure the product data still meets your needs. Not applicable to Half.com. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.ReviewCount	int	Conditionally	The total number of reviews that are available for this product on the eBay Web site. This can be greater than the number of reviews returned by FindProducts. In a future release, we will provide the capability to retrieve details about reviews. Always returned when Product is returned. Min: 0. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.StockPhotoURL	anyURI	Conditionally	Fully qualified URL for a stock image (if any) that is associated with the eBay catalog product. The URL is for the image eBay usually displays in product search results (usually 70px tall). It may be helpful to calculate the dimensions of the photo programmatically before displaying it. Only returned if a URL is available for the product. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
Product.Title	string	Conditionally	The title of the product, as specified in the catalog. Always returned when Product is returned. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.
TotalProducts	int	Always	The total number of matching products found. (If more than 2000 products are found, the call fails with an error.) Min: 0. Max: 2000. IncludeSelector: Details, DomainHistogram, Items. Also returned if IncludeSelector is not provided on input.

FindProducts Detail Controls

Detail Control: IncludeSelector

The IncludeSelector input field influences which call-specific fields may be returned. (All standard output fields are returned regardless of IncludeSelector.)

none	The field is returned if IncludeSelector is not specified on input.
Y	The field is always returned.
(Y)	The field is conditionally returned. See the field description for clarification of conditions.

eBay Shopping API Call Reference Version 579

Best Practices

More Tips

eBay Shopping API
Call Reference Version 579