FindProducts

Note: All calls in the Shopping API have been deprecated and will be decommissioned on February 5, 2025. An alternative to this API is the Browse API, which also has advanced search capabilities.

Note: Developers using Shopping API calls must authenticate with an OAuth application access token in the HTTP header X-EBAY-API-IAF-TOKEN and use OAuth application access tokens with a scope that includes https://api.ebay.com/oauth/api_scope. See the client credentials grant flow topic for more information on generating and managing OAuth application access tokens. See the Specifying OAuth scopes topic for more information on OAuth scopes.

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

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

<?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: total number varies based on search criteria, but can be as high as 800+. 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: total number varies based on search criteria, but can be as high as 10,000+. 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 type 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 type 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) This value is used to sort results in ascending (low to high) order. CustomCode (in) Reserved for internal or future use. Descending (in) This value is used to sort results in descending (high to low) order.

Standard Input Fields

MessageID

string

Optional

If you pass a value into the MessageID field in a request, the same value is returned in CorrelationID field 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).

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">
  <!-- 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: Reflects the value passed in request; can be as high as 10,000+. 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 Product Details section of the eBay catalog product page is displayed in this field. The user can grab this URL, paste it in a browser, and view the Product Details section of the eBay catalog product page for the corresponding eBay marketplace site. Note that some catalog product pages will have active listings associated with them, and some will not. It is also possible that some catalog product may not contain stock photos. 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 defined. 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). This field is not returned at all if there are no product reviews available for the catalog product. Min: 1. 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 (DisplayStockPhotos should return as `true`. 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. Max length: 80. 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. This value can be quite larger than the total number of catalog products returned per page, which 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: 1. 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 Error Handling
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 version of the API call that eBay used to process the request. Note: Note that some calls are not always updated with each WSDL release, so it is possible that version numbers will differ by API call. 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.

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

Output Field	none	DomainHistogram
ApproximatePages	Y	Y
DomainHistogram	-	Y
DomainHistogram.Domain	-	Y
DomainHistogram.Domain.Count	-	(Y)
DomainHistogram.Domain.Name	-	(Y)
MoreResults	Y	Y
PageNumber	Y	Y
Product	Y	Y
Product.DetailsURL	Y	-
Product.DisplayStockPhotos	Y	-
Product.DomainName	(Y)	-
Product.ItemSpecifics	(Y)	-
Product.ItemSpecifics.NameValueList	Y	-
Product.ItemSpecifics.NameValueList.Name	(Y)	-
Product.ItemSpecifics.NameValueList.Value	(Y)	-
Product.ProductID	Y	-
Product.ProductState	(Y)	-
Product.ReviewCount	(Y)	-
Product.StockPhotoURL	(Y)	-
Product.Title	Y	-
TotalProducts	Y	Y

DetailLevel

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

Samples

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.

https://open.api.ebay.com/shopping?
   callname=FindProducts&
   responseencoding=XML&
   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
1119 2019-08-02	FindProducts (modified): Shopping API endpoint updated to support 'https' protocol. So, the following production endpoint should be used for all Shopping API calls: https://open.api.ebay.com/shopping. The http://open.api.ebay.com/shopping endpoint will still be supported for the time being, but is subject to be wired off.
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.