eBay Shopping APIVersion 1027

FindProducts


Important: The ItemArray node in the call response is deprecated as of November 2014. Starting in December of 2014, this call may stop returning a list of active items that were listed with the requested product. The call will, however, continue to return product information. The findItemsByProduct call in the Finding API is the preferred method to retrieve active items on eBay marketplaces that were listed with a given product.

This call 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.

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

Usage Details

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 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 site. (To find more listings (if any), use the Finding API.)

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.

FindProducts supports affiliate tracking for members of the eBay Affiliates Program. For information about specifying affiliate parameters, see Affiliate URL Parameters and HTTP Header Values.

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.

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

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.

Related Information

See also the reference documentation for this call:



Input

See also Samples.

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

<?xml version="1.0" encoding="utf-8"?>
<FindProductsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <AvailableItemsOnly> boolean </AvailableItemsOnly>
  <CategoryID> string </CategoryID>
  <DomainName> string </DomainName>
  <!-- ... more DomainName values allowed here ... -->
  <HideDuplicateItems> boolean </HideDuplicateItems>
  <IncludeSelector> string </IncludeSelector>
  <MaxEntries> int </MaxEntries>
  <PageNumber> int </PageNumber>
  <ProductID type="ProductIDCodeType"> ProductIDType (string) </ProductID>
  <ProductSort> ProductSortCodeType </ProductSort>
  <QueryKeywords> string </QueryKeywords>
  <SortOrder> SortOrderCodeType </SortOrder>
  <!-- Standard Input Fields -->
  <MessageID> string </MessageID>
</FindProductsRequest>
Argument Type Occurrence Meaning
Call-specific Input Fields [Jump to standard 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 be empty).

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.
The request requires a single one of these three elements: QueryKeywords, ProductID, or CategoryID, and can only include one of the three.
Max length: 10.
DomainName string Optional,
repeatable: [0..*]
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.
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:
  • Items are listed by the same seller
  • Items have exactly the same item title
  • Items have similar listing formats
    • Auctions: Auction Items, Auction BIN items, Multi-Quantity Auctions, and Multi-Quantity Auctions BIN items
    • Fixed Price: Fixed Price, Multi-quantity Fixed Price, and Fixed Price with Best Offer items
    • Classified Ads

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. For FindProducts, this filter only works when IncludeSelector is set to Items or Details.
Default: false.
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 a single one of these three elements: QueryKeywords, ProductID, or CategoryID, and can only include one of the three.
Max length: 4000.
ProductID
  [ attribute type ]
ProductIDCodeType 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 a single one of these three elements: QueryKeywords, ProductID, or CategoryID, and can only include one of the three.

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: See ProductSort.
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 a single one of these three elements: QueryKeywords, ProductID, or CategoryID, and can only include one of the three.
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.
Standard Input 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.



Output

See also Samples.

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

<?xml version="1.0" encoding="utf-8"?>
<FindProductsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <ApproximatePages> int </ApproximatePages>
  <DomainHistogram> DomainHistogramType
    <Domain> HistogramEntryType
      <Count> int </Count>
      <Name> string </Name>
    </Domain>
    <!-- ... more Domain nodes allowed here ... -->
  </DomainHistogram>
  <DuplicateItems> boolean </DuplicateItems>
  <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 values allowed here ... -->
      </NameValueList>
      <!-- ... more NameValueList nodes allowed here ... -->
    </ItemSpecifics>
    <ProductID type="ProductIDCodeType"> ProductIDType (string) </ProductID>
    <!-- ... more ProductID values allowed here ... -->
    <ProductState> ProductStateCodeType </ProductState>
    <ReviewCount> int </ReviewCount>
    <StockPhotoURL> anyURI </StockPhotoURL>
    <Title> string </Title>
  </Product>
  <!-- ... more Product nodes allowed here ... -->
  <TotalProducts> int </TotalProducts>
  <!-- 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 allowed here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes allowed here ... -->
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
</FindProductsResponse>
Return Value Type Occurrence Meaning
Call-specific Output Fields [Jump to standard 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: none (not controlled by IncludeSelector)
DomainHistogram DomainHistogramType Always 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 Always,
repeatable: [1..*]
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 Always 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 Always 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
DuplicateItems boolean Conditionally Indicates whether there are duplicated items not returned by this response when HideDuplicateItems is true in the request.

IncludeSelector: Details, Items
MoreResults boolean Always If true, more pages of results are available. That is, PageNumber is less than ApproximatePages.

IncludeSelector: none (not controlled by IncludeSelector)
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: none (not controlled by IncludeSelector)
Product CatalogProductType Always,
repeatable: [1..20]
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 by default. (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: none (not controlled by IncludeSelector)
Product.DetailsURL anyURI Always 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: none (not controlled by IncludeSelector)
Product.DisplayStockPhotos boolean Always 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: none (not controlled by IncludeSelector)
Product.DomainName string Always 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: none (not controlled by IncludeSelector)
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 the Finding API. Only returned when you search by ProductID (and you pass Items or Details in IncludeSelector).
Min: 0.

IncludeSelector: Details, Items
Product.ItemSpecifics NameValueListArrayType Always 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: none (not controlled by IncludeSelector)
Product.ItemSpecifics
  .NameValueList
NameValueListType Always,
repeatable: [1..*]
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).

In multi-variation listings, the same name cannot appear in both the VariationSpecifics node and in the ItemSpecifics node.

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: none (not controlled by IncludeSelector)
Product.ItemSpecifics
  .NameValueList.Name
string Always The name of the item specific.

This field is returned only in responses if the seller included an item specific Name in the listing. However, if the seller didn't also include a corresponding value for the item specific, it is best to not display the name to 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.

Note: Ignore item specifics with SIFFTAS in the name. These are for internal use by eBay and aren't meaningful to users.

IncludeSelector: none (not controlled by IncludeSelector)
Product.ItemSpecifics
  .NameValueList.Value
string Always,
repeatable: [1..*]
A value for the item specific.

This field is only returned in responses if the seller included a value for an item specific. In the GetSingleItem response, 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: none (not controlled by IncludeSelector)
Product.ProductID ProductIDType (string) Always,
repeatable: [1..*]
The eBay ID or the ISBN, EAN, or UPC value (if returned) associated with the product. 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: none (not controlled by IncludeSelector)
Product.ProductID
  [ attribute type ]
ProductIDCodeType Always The eBay ID or the ISBN, EAN, or UPC value (if returned) associated with the product. 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.

For a list of possible enumeration values, see ProductIDCodeType.
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).

Applicable values: See ProductState.
Code so that your app gracefully handles any future changes to this list.

IncludeSelector: none (not controlled by IncludeSelector)
Product.ReviewCount int Always 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: none (not controlled by IncludeSelector)
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: none (not controlled by IncludeSelector)
Product.Title string Always The title of the product, as specified in the catalog. Always returned when Product is returned.

IncludeSelector: none (not controlled by IncludeSelector)
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: none (not controlled by IncludeSelector)
Standard Output 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 the Ack field.

Applicable values:

CustomCode
(out) Reserved for internal or future use.
Failure
(out) This value indicates that the call request processing failed.
Success
(out) This value indicates that the call request was processed successfully without any issues.
Warning
(out) This value indicates that the call request was successful, but processing was not without any issues. These issues can be checked in the Errors container, that will also be returned when one or more known issues occur with the call request.

(Not all values in AckCodeType apply to this field.)

Code so that your app gracefully handles any future changes to this list.
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 Conditionally,
repeatable: [0..*]
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.

Code so that your app gracefully handles any future changes to this list.

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 Conditionally,
repeatable: [0..*]
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 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.
Errors.ErrorParameters.Value string Conditionally This is the value of the request parameter noted in the ParamID attribute. So, if the ParamID value was ItemID, the value in this field would be the actual value of that ItemID.
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.

Code so that your app gracefully handles any future changes to this list.

See:
    Errors by Number
    Checklist for Going Live for more information see the eBay Features 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 Schema Versioning Strategy.



Detail Controls


IncludeSelector

The IncludeSelector input field gives you control over which call-specific output fields may be returned from your queries. IncludeSelector accepts a set of preset values, each of which permits the return of a different set of fields. (All standard output fields are returned regardless of IncludeSelector.)

The table below details the fields that each IncludeSelector value controls. In addition, the table includes a none column that shows the fields that are not controlled by IncludeSelector settings. Note that some fields are returned only when certain conditions are met; see the associated field documentation for a clarification of these conditions.

YThe field is always returned.
(Y)The field is conditionally returned. See the field documentation for clarification of conditions.

Output Field none Details DomainHistogram Items
ApproximatePagesY---
DomainHistogram--Y-
DomainHistogram.Domain--Y-
DomainHistogram.Domain.Count--Y-
DomainHistogram.Domain.Name--Y-
DuplicateItems-(Y)-(Y)
MoreResultsY---
PageNumberY---
ProductY---
Product.DetailsURLY---
Product.DisplayStockPhotosY---
Product.DomainNameY---
Product.ItemCount-(Y)-(Y)
Product.ItemSpecificsY---
Product.ItemSpecifics.NameValueListY---
Product.ItemSpecifics.NameValueList.NameY---
Product.ItemSpecifics.NameValueList.ValueY---
Product.ProductIDY---
Product.ProductState(Y)---
Product.ReviewCountY---
Product.StockPhotoURL(Y)---
Product.TitleY---
TotalProductsY---


DetailLevel

This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.



Samples

New to making API calls? Please see Making a Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample: Basic Call

Retrieves products in the eBay catalog that contain the keyword specified in the call request.

Input

This example specifies a keyword string ("harry potter") to obtain a list of products in the eBay catalog that are associated with that keyword. Two other filter parameters are used: including the AvailableItemsOnly boolean parameter and setting its value to true will limit the products that are returned to only those currently available for sale through an active eBay listing.; and including the MaxEntries filter with its value set to 2 will limit the amount of product entries to two.

URL format. See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.
http://open.api.ebay.com/shopping?
   callname=FindProducts&
   responseencoding=XML&
   appid=YourAppIDHere&
   siteid=0&
   version=967&
   QueryKeywords=harry%20potter&
   AvailableItemsOnly=true&
   MaxEntries=2

   Here is the same input in XML format. Note that this does not include standard values.

XML format.

<?xml version="1.0" encoding="utf-8"?>
<FindProductsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <QueryKeywords>Harry Potter</QueryKeywords>
  <MaxEntries>2</MaxEntries>
  <AvailableItemsOnly>true</AvailableItemsOnly>
</FindProductsRequest>

Output

Two products are returned in the response (a Product node is returned for each one). As indicated by the DomainName value under each Product node, one of these products is a DVD, and the the other is a book.

XML format.
<?xml version="1.0" encoding="UTF-8"?>

  <FindProductsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
   <Timestamp>2016-05-07T23:09:03.495Z</Timestamp>
   <Ack>Success</Ack>
   <Build>e967_core_Bundled_6206837_R1</Build>
   <Version>967</Version>
   <ApproximatePages>207</ApproximatePages>
   <MoreResults>true</MoreResults>
   <PageNumber>1</PageNumber>
   <Product>
    <DomainName>DVDs</DomainName>
    <DetailsURL>http://syicatalogs.ebay.com/ws/eBayISAPI.dll?PageSyiProductDetails&IncludeAttributes=1&ShowAttributesTable=1&ProductMementoString=92460:2:1049:1489297318:138039228:f19efe1397d028d65cd2b81e1112fcfa:1:1:1:1382045716</DetailsURL>
    <DisplayStockPhotos>true</DisplayStockPhotos>
    <ProductID type="Reference">62923188</ProductID>
    <ProductID type="UPC">012569593268</ProductID>
    <ItemSpecifics>
     <NameValueList>
      <Name>Rating</Name>
      <Value>PG-13</Value>
     </NameValueList>
     <NameValueList>
      <Name>Leading Role</Name>
      <Value>Daniel Radcliffe</Value>
      <Value>Emma Watson</Value>
      <Value>Rupert Grint</Value>
     </NameValueList>
     <NameValueList>
      <Name>Format</Name>
      <Value>DVD</Value>
     </NameValueList>
    </ItemSpecifics>
    <ReviewCount>56</ReviewCount>
    <StockPhotoURL>http://i11.ebayimg.com/08/c/000/77/43/ade9_6.JPG</StockPhotoURL>
    <Title>Harry Potter and the Order of the Phoenix (2007, DVD)</Title>
   </Product>
   <Product>
    <DomainName>Children's Books</DomainName>
    <DetailsURL>http://syicatalogs.ebay.com/ws/eBayISAPI.dll?PageSyiProductDetails&IncludeAttributes=1&ShowAttributesTable=1&ProductMementoString=88519:2:1055:1565202560:138165260:59e578afaa39f41a8361fe9b641f3352:1:1:1:1378670148</DetailsURL>
    <DisplayStockPhotos>true</DisplayStockPhotos>
    <ProductID type="Reference">59049480</ProductID>
    <ProductID type="ISBN">0545010225</ProductID>
    <ProductID type="ISBN">9780545010221</ProductID>
    <ItemSpecifics>
     <NameValueList>
      <Name>Binding</Name>
      <Value>Hardcover</Value>
     </NameValueList>
     <NameValueList>
      <Name>Author</Name>
      <Value>J. K. Rowling</Value>
     </NameValueList>
    </ItemSpecifics>
    <ReviewCount>181</ReviewCount>
    <StockPhotoURL>http://i20.ebayimg.com/05/c/000/77/3c/71fc_6.JPG</StockPhotoURL>
    <Title>Harry Potter and the Deathly Hallows by J. K. Rowling (2007)</Title>
   </Product>
   <TotalProducts>414</TotalProducts>
  </FindProductsResponse>
 



Change History

Change Date Description
955
2016-02-12
  • BuyerPaymentMethodCodeType (modified): The Moneybookers, ProPay, and Paymate enumeration values have been deprecated, and will no longer be returned in any calls.
945
2015-10-15
  • BuyerPaymentMethodCodeType (modified): Moneybookers, ProPay, or Paymate will no longer be accepted as valid PaymentMethods for new listings. However, these payment methods will still be allowed for existing listings, so these values may still get returned until these payment methods are completely removed from all listings.
899
2014-11-04
  • ItemArray (deprecated): In this release, the ItemArray field was deprecated. To retrieve items listed on eBay with a given product, use findItemsByProduct in the Finding API.
897
2014-10-21
  • SiteCodeType (modified): 'Russia' added as enumeration value to support selling on the new Russia site.
873
2014-05-06
  • Item.ShippingCostSummary (doc change): This container and its children do not provide reliable shipping cost information when returned by the FindProducts call. If a listing has shipping costs, use the GetShippingCosts call to get more details about the services and costs that the seller is offering.
637
2009-09-30
  • ShippingCostSummaryType.ListedShippingServiceCost (added): The listed shipping cost for an item.
581
2008-09-03
  • HideDuplicateItems, DuplicateItems (added): When HideDuplicateItems is specified in the request, any duplicate item listings are filtered from the results. DuplicateItems is true in the response when duplicate items were filtered from the search results.
565
2008-05-14
  • CategoryID (added): You can now filter your results by CategoryID.
  • ProductID (modified): Starting in May 2008, some sites will start migrating some catalogs to a new provider. If you pass in an older product reference ID, eBay will return a corresponding newer product if available.
  • Product.ProductState (added): Identifies a product that has been updated or marked for replacement or deletion.
527
2007-08-22
  • ListingType (modified): When you use the IncludeSelector field to specify that items are returned in the response, the listing type of an item is returned.
525
2007-08-08
  • (added) New call.