eBay Shopping APIVersion 1099

FindProducts


Important: In the past, this call retrieved details on active listings that were associated with the retrieved catalog products. However, now this call only retrieves catalog product data, and no longer retrieves any listing-related data. If a user would like to retrieve active listings that are associated with a specific eBay catalog product, they can make a findItemsByProduct call in the Finding API. In the findItemsByProduct call request, the user passes in the eBay product ID (ePID) value into the productId field.


This call searches for eBay catalog product records, based on a specified query string. There are other filters available as well. When creating, revising, or relisting an item, sellers can use eBay catalog products to prefill product title, product aspects, and any stock photo defined in the catalog product definition. Keep in mind that eBay does not have catalog product records for every type of product across all eBay categories.

Usage Details

This call is designed to be useful to applications that support shopping comparisons or basic supply and demand data. It returns basic catalog product information, such as the product title, stock photo (if any), and Item Specifics. Item Specifics are well-known aspects of products that describe the product in a structure manner. For example, a book's Item Specifics might include a name-value pair like Publication Year=2017, and a field like Binding=Hardcover. An event ticket's Item Specifics might include name-value pairs like EventType=Concert and Venue=The Fillmore.

A typical use for this call is to pass in keywords (related to the product) in the QueryKeywords field, and then eBay retrieves catalog products with product titles, product descriptions, and/or Item Specifics that match these keywords.

If a user already has the unique identifier of an eBay catalog product (known as an eBay Product ID, or ePID), the user can pass in this identifier into the ProductID field in the FindProducts request to get more information about this catalog product, including product title, Item Specifics, link to stock photo (if any), and a link to the product page on the eBay marketplace.

Every eBay catalog product has a unique identifier (an ePID), and many products also have one or mor Global Trade Item Numbers (GTINs), such as UPC, EAN, ISBN, or MPN (Manufacturer Part Number). So, the ProductID field in the FindProducts request can also be used to search for catalog products by GTIN value. The product identifier type is identified using the ProductID field's type attribute.

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.



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 -->
  <CategoryID> string </CategoryID>
  <DomainName> string </DomainName>
  <!-- ... more DomainName values allowed here ... -->
  <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]
CategoryID string Optional This field is included to restrict the catalog products that are returned. Only the catalog products associated with this category ID are returned.

This field is generally used with the QueryKeywords field.

The GetCategories or GetSuggestedCategories calls of the Trading API can be used to retrieve CategoryID values.
DomainName string Optional,
repeatable: [0..*]
Important: The use of domain histograms and DomainName filters is no longer recommended, as the domain histogram data that is returned in the response, and filtering by domain logic is no longer reliable.

An eBay domain to search in. This is like searching a section of the eBay catalog. If this field is not included, the catalog product search is conducted across all defined eBay domains. The user can use multiple DomainName filters to search multiple defined eBay domains. 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 retrieve valid domain names, first use this call with your query string specified in QueryKeywords, and the IncludeSelector field's value set to DomainHistogram. After retrieving all eBay defined domain names for the query string under the DomainHistogram container, the user can select the eBay domains relevant to the product they're searching for, and then they can do another FindProducts call with one or more DomainName filters.

Generally, DomainName filter(s) are only useful for query string searches using QueryKeywords field. If you are searching for a specific catalgo product based on eBay Product ID (ePID) or a Global Trade Item Number (GTIN), such as a UPC, ISBN, or EAN, a lt;b>DomainName filter is not needed.
IncludeSelector string Optional Important: The use of domain histograms and DomainName filters is no longer recommended, as the domain histogram data that is returned in the response, and filtering by domain logic is no longer reliable. DomainHistogram is the only value that can be used for IncludeSelector, so this filter has no practical use, and may be deprecated in the near future.

This filter is included and set to DomainHistogram if the user would like to view domain histogram data in the response. The DomainHistogram container that is returned displays all eBay category domains associated with all eBay catalog products that are retrieved. The count of eBay catalog products associated with each domain is also shown under each Domain container. If this field is omitted, only the catalog product records and pagination data is returned.

Important: Historically, the IncludeSelector field supported two other values - Items and Details. However, both of these enumeration values controlled the data that was returned through the ItemArray container, and this container is no longer returned at all. The FindProducts call now only retrieves one or more eBay catalog products, and no longer retrieves active listing data related to these catalog products. The Items or Details values will have no effect is used.
MaxEntries int Optional This field is used to limit/control the maximum number of catalog products that are returned per page of data in a single call. This is generally used with string query searches using the QueryKeywords field.

If this field is not used, its value defaults to '1', and only one catalog product is returned. The user may want to look at the TotalProducts field's value to see how many eBay catalog products matched the search criteria, and then the user may want to do another call, possibly refining/narrowing the search with a more precise query string in the QueryKeywords field, or perhaps with one or more DomainName filters.

If the MoreResults field is returned as true, this indicates that more than one page of results are available based on the current search criteria, so the user will have to make additional calls to view additional pages of results, changing the PageNumber value as needed.
Min: 1. Max: 300+ (total number may vary based on search criteria). Default: 1.
PageNumber int Optional This field is used to control the page number of results to retrieve in the call. If this field is omitted, the first page of results is returned by default. You know that you have additional pages or results if the MoreResults field is returned as true.

This field takes a positive integer value equal to or lower than the number of pages available. The total number of pages in the results set is shown in the ApproximatePages field of the response.
Min: 1. Max: 2000. Default: 1.
ProductID ProductIDType (string) Conditional Use this field to find a catalog product (or products) associated with an eBay Product ID (ePID) or a Global Trade Item Number (GTIN), such as a UPC, ISBN, or EAN. The product identifier is expressed as a string value, and the type of product identifier is expressed in the type attribute.

See the ProductIDCodeType definition to view the supported enumeration values for the lt;b>typelt;/b> attribute. Note that it is possible that there may be multiple eBay catalog products associated with the same GTIN value, but there can only be one eBay catalog product associated with a specific ePID value.
ProductID
  [ attribute type ]
ProductIDCodeType Conditional Use this field to find a catalog product (or products) associated with an eBay Product ID (ePID) or a Global Trade Item Number (GTIN), such as a UPC, ISBN, or EAN. The product identifier is expressed as a string value, and the type of product identifier is expressed in the type attribute.

See the ProductIDCodeType definition to view the supported enumeration values for the lt;b>typelt;/b> attribute. Note that it is possible that there may be multiple eBay catalog products associated with the same GTIN value, but there can only be one eBay catalog product associated with a specific ePID value.

For a list of possible enumeration values, see ProductIDCodeType.
ProductSort ProductSortCodeType Optional This field allows the user to control the order in which the retrieved catalog products are displayed in the response. If this field is not included, the results are sorted by the catalog product's popularity.

See the ProductSortCodeType definition to view the available sort values.

This field can be used in conjunction with the SortOrder field. The SortOrder field controls whether catalog products are returned in ascending or descending order (according to the ProductSort value). If neither ProductSort nor SortOrder fields are used, catalog products are sorted by popularity in descending order.
Default: Popularity.

Applicable values: See ProductSort.
QueryKeywords string Conditional This string field is used to defined a query string using one or more keywords. When you use a keyword search, eBay searches the product catalog for matching words in the product title, description, and/or Item Specifics, and it returns a list of matching catalog products. If used, the response will also be affected by any eBay domains that are specified through one or more DomainName filters.

The query string must contain at least three 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 too many results are returned, you may want to refine the search by passing in more keywords and/or by using one or more DomainName filters. Using a CategoryID value is also an option, as this will return only catalog products associated with that eBay category.

If you know your product's UPC, EAN, or ISBN, you may want to use the ProductID field instead of the QueryKeywords field.


Max length: 350.
SortOrder SortOrderCodeType Optional This field is used to control whether catalog products are returned in ascending or descending order (according to the ProductSort value). If neither ProductSort nor SortOrder fields are used, catalog products are sorted by popularity in descending order.
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>
  <MoreResults> boolean </MoreResults>
  <PageNumber> int </PageNumber>
  <Product> CatalogProductType
    <DetailsURL> anyURI </DetailsURL>
    <DisplayStockPhotos> boolean </DisplayStockPhotos>
    <DomainName> string </DomainName>
    <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 in the results set based on the current search criteria. The number of pages in the results set will be determined by how many catalog products are found based on the search criteria (QueryKeywords string, DomainName filter(s), and CategoryID restriction), and the number of catalog products to return on each page of results (set in the MaxEntries field). If 200 catalog products were found (as shown in the TotalProducts field), and the MaxEntries value is 25 (25 catalog products per page), the ApproximatePages value will be 8 (200 (records)/25 (records per page) = 8 (pages).

IncludeSelector: none (not controlled by IncludeSelector)
DomainHistogram DomainHistogramType Always Important: The use of domain histograms and DomainName filters is no longer recommended, as the domain histogram data that is returned in the response, and filtering by domain logic is no longer reliable.
This container consist of an array of eBay category domains, and the number of catalog products that belong to each eBay category domain. This array is only returned if the IncludeSelector field is included in the call request and set to a value of DomainHistogram.

To retrieve valid domain names, first use this call with your query string specified in QueryKeywords, and the IncludeSelector field's value set to DomainHistogram. After retrieving all eBay defined domain names for the query string under the DomainHistogram container, the user can select the eBay domains relevant to the product they're searching for, and then they can do another FindProducts call with one or more DomainName filters.

Generally, DomainName filter(s) are only useful for query string searches using QueryKeywords field. If you are searching for a specific catalog product based on an eBay Product ID (ePID) or a Global Trade Item Number (GTIN), such as a UPC, ISBN, or EAN, a lt;b>DomainName filter is not needed.

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 Conditionally This is the number of eBay catalog products associated with eBay category domain. If an eBay catalog product is mapped to more than one eBay category domain, it is counted separately for each domain. For example, if the same eBay catalog product appears in both Children's Books and Fiction Books domains, the count for both of these domains will include that eBay catalog product.

IncludeSelector: DomainHistogram
DomainHistogram.Domain.Name string Conditionally This is the name of eBay category domain. An eBay catalog product can be mapped to more than one eBay category domain.

IncludeSelector: DomainHistogram
MoreResults boolean Always This boolean value is returned as true if more pages of catalog product records exist for the current search criteria, and false if the current page or results is the only or last page in the results set based on the current search criteria.

If more pages of results are available (value is true), it is advised that the user look at the PageNumber value and at the ApproximatePages value, as this will give the user an idea of how many more pages of results exist based on the current search criteria. After having this knowledge, it is up to the user whether to refine the search a little more to retrieve less results, or perhaps increase the MaxEntries integer value in the call request to retrieve more catalog products per page, or just go ahead and make multiple FindProducts calls to view all pages of results, iterating the PageNumber integer value in the call request by '1' with each subsequent call.

IncludeSelector: none (not controlled by IncludeSelector)
PageNumber int Always This integer value shows the current page number of the results set that is being displayed. The number of pages in the results set depends on how many catalog products exist based on the search criteria, and how many catalog products are being returned per page (set in the MaxEntries field in the call request). The total number of pages in the results set is shown in the ApproximatePages field.

The PageNumber value in the response always reflects the PageNumber value that is set in the call request, or, if the PageNumber field is not used in the call request, the first (and perhaps only) page is returned by default.

If there are multiple pages in the results set, and the user wants to review multiple pages, multiple FindProducts calls are required, iterating the PageNumber integer value in the call request by '1' with each subsequent call.
Min: 1. Max: 2000.

IncludeSelector: none (not controlled by IncludeSelector)
Product CatalogProductType Always,
repeatable: [1..*]
A Product container is returned for each eBay catalog product that matches the search criteria. The Product container consists of specific data about the catalog product, including the product title, product identifiers (ePID and any GTIN value(s)), product aspects, a link to eBay product page, and links to stock photos (if any).

The number of catalog products returned is dependent on the search criteria in the request. Searches based on a QueryKeywords string will generally return multiple catalog products, but a search based on an eBay Product ID (set in the ProductID field) should only return one catalog product. The number of catalog products returned per page will also depend on the MaxEntries value set in the call request.

IncludeSelector: none (not controlled by IncludeSelector)
Product.DetailsURL anyURI Always The fully-qualified URL to the eBay product page is displayed in this field. The user can grab this URL, paste it in a browser, and view the product page on the eBay marketplace. Note that some product pages will have active listings associated with them, and some will not.

Applications can include this URL as a link in product search results, so that end users can view additional descriptive details about the product.

IncludeSelector: none (not controlled by IncludeSelector)
Product.DisplayStockPhotos boolean Always If this field is returned as true, there is a stock photo associated with the catalog product, and the URL to this image file is shown in the StockPhotoURL field. If this field is returned as false, there is no stock photo associated with the catalog product.

Sellers should be aware that if no stock photo exists for a catalog product, the seller must add at least one of their own photos when creating a listing (based on that catalog product), as all eBay listings must have at least one image.

An application incorporating a graphical user interface can use this flag to determine when to hide customized stock photo widgets.

This field is always returned in each Product container.

IncludeSelector: none (not controlled by IncludeSelector)
Product.DomainName string Conditionally The name of the eBay category-related domain most closely associated with the catalog product. If the catalog product is associated with multiple category-related domains, eBay returns the most applicable domain (as determined by eBay).

This field is only returned if a catalog product is associated with one or more category-related domains, and if eBay has this data available.


IncludeSelector: none (not controlled by IncludeSelector)
Product.ItemSpecifics NameValueListArrayType Conditionally This array contains a list of Item Specifics (also referred to as Product Asepcts) defined for the catalog product. Item Specifics provide desciptive details of an item in a structured manner.

Scanning Item Specific name-value pairs for catalog products in the response can be useful if the user would like to expand the query string to return more precise results. For example, if a user specified 'iPhone 8' as the query string in the call request, but after seeing too many catalog products of phones in different colors, and with different storage capacities in the response, the user could run another call, but expand the query string to 'iphone 8 256GB Gray'. In this case, the user would only see iPhone 8s that are gray and have 256 GB of storage capacity.

Important: Most eBay catalog products have at least one to a few Item Specifics defined, but it is possible that some retrieved catalog products will not have any Item Specifics.

IncludeSelector: none (not controlled by IncludeSelector)
Product.ItemSpecifics
  .NameValueList
NameValueListType Always,
repeatable: [1..*]
This list is an array of Item Specifics name-value pairs for an eBay Catalog product (if FindProducts is used) or Item Specifics name-value pairs for a single-variation listing or individual variation within a multiple-variation listing (if GetSingleItem or GetMultipleItems is used).

For example, Item Specifics for a motor vehicle might include a field like Make=Toyota (where Make is returned in Name field, and Toyota is returned in Value field) and Model=Prius (where Model is returned in Name field, and Prius is returned in Value field).

In multiple-variation listings, the same name cannot appear in both the ItemSpecifics node and Variation.VariationSpecifics nodes. Common aspects for all variations within the multiple-variation listings will appear in the ItemSpecifics node, and aspects unique to individual variations within the multiple-variation listings will appear in the Variation.VariationSpecifics nodes.

For GetSingleItem, the user can use the NameValueList container in the call input to identify one or more variations to retrieve from a specific multiple-variation listing.

IncludeSelector: none (not controlled by IncludeSelector)
Product.ItemSpecifics
  .NameValueList.Name
string Conditionally The name of the Item Specific for either an eBay Catalog Product (FindProducts call only), a single-variation listing, and individual variation within a multiple-variation listing, or a Parts Compatibility aspect for a motor vehicle part or accessory listing.

Note: To control the data that is returned in a GetSingleItem or GetMultipleItems response, the IncludeSelector filter should be included. To see listing-level Item Specifics, include the IncludeSelector field and set its value to ItemSpecifics. To see variation-level Item Specifics (only applicable for multiple-variation listings), include the IncludeSelector field and set its value to Variations. To see Parts Compatibility name/value pairs (only applicable for motor vehicle part or accessory listings with a compatible vehicle list), include the IncludeSelector field and set its value to Compatibility.

IncludeSelector: none (not controlled by IncludeSelector)
Product.ItemSpecifics
  .NameValueList.Value
string Conditionally,
repeatable: [0..*]
The corresponding value of an Item Specific for either an eBay Catalog Product (FindProducts call only), a single-variation listing, an individual variation within a multiple-variation listing, or a Parts Compatibility aspect for a motor vehicle part or accessory listing.

IncludeSelector: none (not controlled by IncludeSelector)
Product.ProductID ProductIDType (string) Always,
repeatable: [1..*]
At least one ProductID field is always returned with each Product container, as this value is the unique identifier (ePID) of the eBay catalog product. Any Global Trade Item Numbers (such as ISBN, EAN, UPC, or MPN) are also returned if defined in the catalog product record. The field's type attribute indicates the product identifier type. For ePIDs, the type attribute value is Reference. The ISBN, EAN, and UPC values can be useful as keys if your application is comparing products across different sites.

See the ProductIDCodeType definition to view the applicable enumeration values for the lt;b>typelt;/b> attribute.

IncludeSelector: none (not controlled by IncludeSelector)
Product.ProductID
  [ attribute type ]
ProductIDCodeType Always At least one ProductID field is always returned with each Product container, as this value is the unique identifier (ePID) of the eBay catalog product. Any Global Trade Item Numbers (such as ISBN, EAN, UPC, or MPN) are also returned if defined in the catalog product record. The field's type attribute indicates the product identifier type. For ePIDs, the type attribute value is Reference. The ISBN, EAN, and UPC values can be useful as keys if your application is comparing products across different sites.

See the ProductIDCodeType definition to view the applicable enumeration values for the lt;b>typelt;/b> attribute.

For a list of possible enumeration values, see ProductIDCodeType.
Product.ProductState ProductStateCodeType Conditionally The enumeration value in this field provides information on the current state of the catalog product record. This field is generally only returned if the catalog product record was recently updated, is due for an update, or if the record is scheduled to be deleted.

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 Conditionally This integer value indicates the total number of reviews that are available for the catalog product on the eBay Web site. Not all products will have reviews on an eBay marketplace, but if reviews are available for a catalog product, product reviews should be accessible from the catalog product page (see corresponding DetailsURL field).

IncludeSelector: none (not controlled by IncludeSelector)
Product.StockPhotoURL anyURI Conditionally The fully-qualified URL to the catalog product's stock photo. This field is only returned if a stock photo exists for the eBay catalog product. Generally, this is the image that eBay displays in product-based search results.

IncludeSelector: none (not controlled by IncludeSelector)
Product.Title string Always The title of the product, as it is defined in the catalog product record. This field is always returned with each Product container.

IncludeSelector: none (not controlled by IncludeSelector)
TotalProducts int Always This integer value is the total number of catalog products that match the current search criteria. Keep in mind that the total number of catalog products returned per page is controlled by the MaxEntries value set in the call request. The user can also look at the ApproximatePages field to see how many pages of results exist for the current search criteria.

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 DomainHistogram
ApproximatePagesYY
DomainHistogram-Y
DomainHistogram.Domain-Y
DomainHistogram.Domain.Count-(Y)
DomainHistogram.Domain.Name-(Y)
MoreResultsYY
PageNumberYY
ProductYY
Product.DetailsURLY-
Product.DisplayStockPhotosY-
Product.DomainName(Y)-
Product.ItemSpecifics(Y)-
Product.ItemSpecifics.NameValueListY-
Product.ItemSpecifics.NameValueList.Name(Y)-
Product.ItemSpecifics.NameValueList.Value(Y)-
Product.ProductIDY-
Product.ProductState(Y)-
Product.ReviewCount(Y)-
Product.StockPhotoURL(Y)-
Product.TitleY-
TotalProductsYY


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
1085
2018-10-26
  • FindProductsRequestType (modified): The AvailableItemsOnly and HideDuplicateItems filters are no longer applicable because the FindProducts call no longer retrieves any active listings associated with the retrieved catalog products.
0955
2016-02-12
  • BuyerPaymentMethodCodeType (modified): The Moneybookers, ProPay, and Paymate enumeration values have been deprecated, and will no longer be returned in any calls.
0945
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.
0899
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.
0897
2014-10-21
  • SiteCodeType (modified): 'Russia' added as enumeration value to support selling on the new Russia site.
0873
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.
0637
2009-09-30
  • ShippingCostSummaryType.ListedShippingServiceCost (added): The listed shipping cost for an item.
0581
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.
0565
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.
0527
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.
0525
2007-08-08
  • (added) New call.