findItemsByProduct

Note: All calls in the Finding 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.

This call searches for items on eBay using specific eBay product values.

Usage Details

To use this call, input a product number using the productId field. Products on eBay fall into the following categories:

• ReferenceID
  The ePID, a global reference ID for an eBay catalog product. The ePID is a fixed reference to a product (regardless of version). Use FindProducts in the Shopping API to discover valid ePID values that you can use as input to findItemsByProduct. Each product in the response includes a reference ID.
• ISBN
  The ISBN-10 or ISBN-13 value for books. If you know a book's ISBN, you can use this instead of the eBay Reference ID to search for that book.
• UPC
  The UPC value for products in Music (e.g., CDs), DVD and Movie, and Video Game categories. If you know a product's UPC number, you can use this value instead of the eBay Reference ID to search for that product.
• EAN
  The EAN value for books (most commonly used in European countries). If you know a book's EAN, you can use this instead of the eBay Reference ID to search for that book.

The findItemsByProduct response contains details about items matching your search criteria. By default, eBay returns a specific set of data in the response to your call. Control findItemsByProduct result sets using the following methods:

• Searching for items available on a specific eBay site
  The GLOBAL-ID URL parameter (or X-EBAY-SOA-GLOBAL-ID HTTP header) specifies the eBay site to use for searches.
• Filtering results with item filters
  You can control your results by specifying item filters (itemFilter) for a variety of properties, including the item condition, number of bids, price range, listing type, and more.
• Including additional data in the response
  Specify one or more outputSelector fields to retrieve more than the default set of response data. For example, you can retrieve seller information for each item, or an aspect histogram.
• Sorting results
  Use sortOrder to specify the order in which returned items are sorted, such as by price or by listing end time.
• Paginating the results
  Use paginationInput to divide the items matching the search criteria into subsets, or "pages," of data.

If you are an eBay affiliate, you can specify your affiliate information using the fields in the affiliate container. By specifying your affiliate information, you can earn commissions on user activity generated from your site. Affiliate data is embedded in the viewItemURL URLs returned in your search results.

For details on these response control mechanisms, refer to findItemsByKeywords.

Related Information

See also the reference documentation for these calls:

• findItemsAdvanced - Finds items by a keyword query and/or category and allows searching within item descriptions.
• findItemsIneBayStores - Finds items in eBay stores. Can search a specific store or can search all stores with a keyword query.

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"?>
<findItemsByProductRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <!-- Call-specific Input Fields -->
  <itemFilter> ItemFilter
    <name> ItemFilterType </name>
    <paramName> token </paramName>
    <paramValue> string </paramValue>
    <value> string </value>
    <!-- ... more value values allowed here ... -->
  </itemFilter>
  <!-- ... more itemFilter nodes allowed here ... -->
  <outputSelector> OutputSelectorType </outputSelector>
  <!-- ... more outputSelector values allowed here ... -->
  <productId type="string"> ProductId (string) </productId>
  <!-- Standard Input Fields -->
  <affiliate> Affiliate
    <customId> string </customId>
    <geoTargeting> boolean </geoTargeting>
    <networkId> string </networkId>
    <trackingId> string </trackingId>
  </affiliate>
  <buyerPostalCode> string </buyerPostalCode>
  <paginationInput> PaginationInput
    <entriesPerPage> int </entriesPerPage>
    <pageNumber> int </pageNumber>
  </paginationInput>
  <sortOrder> SortOrderType </sortOrder>
</findItemsByProductRequest>

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"?>
<findItemsByProductResponse xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <!-- Call-specific Output Fields -->
  <aspectHistogramContainer> AspectHistogramContainer
    <aspect name="string"> Aspect
      <valueHistogram valueName="string"> AspectValueHistogram
        <count> long </count>
      </valueHistogram>
      <!-- ... more valueHistogram nodes allowed here ... -->
    </aspect>
    <!-- ... more aspect nodes allowed here ... -->
    <domainDisplayName> token </domainDisplayName>
    <domainName> string </domainName>
  </aspectHistogramContainer>
  <conditionHistogramContainer> ConditionHistogramContainer
    <conditionHistogram> ConditionHistogram
      <condition> Condition
        <conditionDisplayName> string </conditionDisplayName>
        <conditionId> int </conditionId>
      </condition>
      <count> int </count>
    </conditionHistogram>
    <!-- ... more conditionHistogram nodes allowed here ... -->
  </conditionHistogramContainer>
  <!-- Standard Output Fields -->
  <ack> AckValue </ack>
  <errorMessage> ErrorMessage
    <error> ErrorData
      <category> ErrorCategory </category>
      <domain> string </domain>
      <errorId> long </errorId>
      <exceptionId> token </exceptionId>
      <message> string </message>
      <parameter name="string"> ErrorParameter (string) </parameter>
      <!-- ... more parameter values allowed here ... -->
      <severity> ErrorSeverity </severity>
      <subdomain> string </subdomain>
    </error>
    <!-- ... more error nodes allowed here ... -->
  </errorMessage>
  <itemSearchURL> anyURI </itemSearchURL>
  <paginationOutput> PaginationOutput
    <entriesPerPage> int </entriesPerPage>
    <pageNumber> int </pageNumber>
    <totalEntries> int </totalEntries>
    <totalPages> int </totalPages>
  </paginationOutput>
  <searchResult count="int"> SearchResult
    <item> SearchItem
      <attribute> ItemAttribute </attribute>
      <!-- ... more attribute nodes allowed here ... -->
      <autoPay> boolean </autoPay>
      <charityId> string </charityId>
      <condition> Condition
        <conditionDisplayName> string </conditionDisplayName>
        <conditionId> int </conditionId>
      </condition>
      <country> token </country>
      <discountPriceInfo> DiscountPriceInfo </discountPriceInfo>
      <distance unit="string"> Distance (double) </distance>
      <eBayPlusEnabled> boolean </eBayPlusEnabled>
      <eekStatus> string </eekStatus>
      <!-- ... more eekStatus values allowed here ... -->
      <galleryInfoContainer> GalleryInfoContainer
        <galleryURL gallerySize="GallerySizeEnum"> GalleryURL (anyURI) </galleryURL>
        <!-- ... more galleryURL values allowed here ... -->
      </galleryInfoContainer>
      <galleryPlusPictureURL> anyURI </galleryPlusPictureURL>
      <!-- ... more galleryPlusPictureURL values allowed here ... -->
      <galleryURL> anyURI </galleryURL>
      <globalId> token </globalId>
      <itemId> string </itemId>
      <listingInfo> ListingInfo
        <bestOfferEnabled> boolean </bestOfferEnabled>
        <buyItNowAvailable> boolean </buyItNowAvailable>
        <buyItNowPrice currencyId="string"> Amount (double) </buyItNowPrice>
        <convertedBuyItNowPrice currencyId="string"> Amount (double) </convertedBuyItNowPrice>
        <endTime> dateTime </endTime>
        <gift> boolean </gift>
        <listingType> token </listingType>
        <startTime> dateTime </startTime>
      </listingInfo>
      <location> string </location>
      <paymentMethod> token </paymentMethod>
      <!-- ... more paymentMethod values allowed here ... -->
      <pictureURLLarge> anyURI </pictureURLLarge>
      <pictureURLSuperSize> anyURI </pictureURLSuperSize>
      <postalCode> string </postalCode>
      <primaryCategory> Category
        <categoryId> string </categoryId>
        <categoryName> string </categoryName>
      </primaryCategory>
      <productId> ProductId (string) </productId>
      <returnsAccepted> boolean </returnsAccepted>
      <secondaryCategory> Category
        <categoryId> string </categoryId>
        <categoryName> string </categoryName>
      </secondaryCategory>
      <sellerInfo> SellerInfo
        <feedbackRatingStar> token </feedbackRatingStar>
        <feedbackScore> long </feedbackScore>
        <positiveFeedbackPercent> double </positiveFeedbackPercent>
        <sellerUserName> string </sellerUserName>
        <topRatedSeller> boolean </topRatedSeller>
      </sellerInfo>
      <sellingStatus> SellingStatus
        <bidCount> int </bidCount>
        <convertedCurrentPrice currencyId="string"> Amount (double) </convertedCurrentPrice>
        <currentPrice currencyId="string"> Amount (double) </currentPrice>
        <sellingState> token </sellingState>
        <timeLeft> duration </timeLeft>
      </sellingStatus>
      <shippingInfo> ShippingInfo
        <expeditedShipping> boolean </expeditedShipping>
        <handlingTime> int </handlingTime>
        <oneDayShippingAvailable> boolean </oneDayShippingAvailable>
        <shippingServiceCost currencyId="string"> Amount (double) </shippingServiceCost>
        <shippingType> token </shippingType>
        <shipToLocations> string </shipToLocations>
        <!-- ... more shipToLocations values allowed here ... -->
      </shippingInfo>
      <storeInfo> Storefront
        <storeName> string </storeName>
        <storeURL> anyURI </storeURL>
      </storeInfo>
      <subtitle> string </subtitle>
      <title> string </title>
      <topRatedListing> boolean </topRatedListing>
      <unitPrice> UnitPriceInfo </unitPrice>
      <viewItemURL> anyURI </viewItemURL>
    </item>
    <!-- ... more item nodes allowed here ... -->
  </searchResult>
  <timestamp> dateTime </timestamp>
  <version> string </version>
</findItemsByProductResponse>

aspectHistogramContainer	AspectHistogramContainer	Conditionally	Response container for aspect histograms. outputSelector: AspectHistogram
aspectHistogramContainer   .aspect	Aspect	Conditionally, repeatable: [1..*]	A characteristic of an item in a domain. For example, "Optical Zoom", "Brand", and "Megapixels" could be aspects of the Digital Cameras domain. Aspects are well-known, standardized characteristics of a domain, and they vary from domain to domain (the aspects of "Men's Shoes" are different from those of "Digital Cameras"). A search request on the eBay site will often display aspects and their respective aspect values on the left-had side of a query response. Aspects are extracted from item listing properties (such as item titles and subtitles), and represent the characteristics of active items. Values returned in the Aspect container can be used as inputs to the aspectFilter fields in a query to distill the items returned by the query. eBay generates aspects dynamically from the items currently listed; aspects provide a view into what is currently available on eBay. Because of this, aspect values returned one day cannot be guaranteed to be valid the next day. The following graphic shows how eBay might return a set of aspects for the Digital Cameras domain. In this graphic, "Product Type", "Brand", and "Megapixels" are aspects, and "Point & Shoot", "Canon", and "12.0 to 12.9 MP" are aspect values. Histogram values (item counts) are shown for each aspect value. outputSelector: AspectHistogram
aspectHistogramContainer   .aspect   [ attribute name ]	string	Conditionally	A characteristic of an item in a domain. For example, "Optical Zoom", "Brand", and "Megapixels" could be aspects of the Digital Cameras domain. Aspects are well-known, standardized characteristics of a domain, and they vary from domain to domain (the aspects of "Men's Shoes" are different from those of "Digital Cameras"). A search request on the eBay site will often display aspects and their respective aspect values on the left-had side of a query response. Aspects are extracted from item listing properties (such as item titles and subtitles), and represent the characteristics of active items. Values returned in the Aspect container can be used as inputs to the aspectFilter fields in a query to distill the items returned by the query. eBay generates aspects dynamically from the items currently listed; aspects provide a view into what is currently available on eBay. Because of this, aspect values returned one day cannot be guaranteed to be valid the next day. The following graphic shows how eBay might return a set of aspects for the Digital Cameras domain. In this graphic, "Product Type", "Brand", and "Megapixels" are aspects, and "Point & Shoot", "Canon", and "12.0 to 12.9 MP" are aspect values. Histogram values (item counts) are shown for each aspect value.
aspectHistogramContainer   .aspect.valueHistogram	AspectValueHistogram	Conditionally, repeatable: [0..*]	Container that returns the name of the respective aspect value and the histogram (the number of available items) that share that item characteristic. This value is not returned if there are no matching aspects for the associated domain. outputSelector: AspectHistogram
aspectHistogramContainer   .aspect.valueHistogram   [ attribute valueName ]	string	Conditionally	Container that returns the name of the respective aspect value and the histogram (the number of available items) that share that item characteristic. This value is not returned if there are no matching aspects for the associated domain.
aspectHistogramContainer   .aspect.valueHistogram.count	long	Conditionally	Number of items that share the characteristic the respective aspect value. outputSelector: AspectHistogram
aspectHistogramContainer   .domainDisplayName	token	Conditionally	A buy-side group of items, for example "Shoes." Domains are extracted from item listing properties, such as the title, descriptions, and so on. outputSelector: AspectHistogram
aspectHistogramContainer   .domainName	string	Conditionally	A buy-side group of items that share aspects, but not necessarily an eBay category. For example "Women's Dresses" or "Digital Cameras" could be domains. You can use a domainName to label a set of aspects that you display. Domains are extracted from item listing properties (such as item titles and subtitles). outputSelector: AspectHistogram
conditionHistogramContainer	ConditionHistogramContainer	Conditionally	Response container for condition histograms. Not returned when Condition is specified in itemFilter. That is, only returned when you have not yet narrowed your search based on specific conditions. Only returned when you search the eBay US site (as of February 2011). International items in US search results are included in the histogram counts. outputSelector: ConditionHistogram
conditionHistogramContainer   .conditionHistogram	ConditionHistogram	Conditionally, repeatable: [0..*]	Statistical (item count) information on the condition of items that match the search criteria (or specified category). For example, the number of brand new items that match the query. Each conditionHistogram specifies one condition and the number of matching items found. The list of all conditionHistogram containers returned represents the union of all conditions that were found in the item results. For example, if items were found in different categories, and if those categories support different sets of item conditions, then all those conditions are returned in the list, regardless of category. If multiple items use the same condition ID, but some items use different display names for that condition, the histogram shows the site's default display name for that condition. This means that the condition name in a histogram may not always exactly match the condition names on the counted items. outputSelector: ConditionHistogram
conditionHistogramContainer   .conditionHistogram.condition	Condition	Conditionally	The name and unique ID of the item condition for which the count is being displayed. outputSelector: ConditionHistogram
conditionHistogramContainer   .conditionHistogram.condition   .conditionDisplayName	string	Conditionally	The human-readable label for the item condition. Display names are localized for the site on which they're listed (not necessarily the site on which they're viewed). In item results, this is only returned when the seller specified the item's condition using a structured format eBay recognizes. When conditionId is also present: Most categories use the same display name for the same condition ID. Some categories may override the display name based on buyer expectations for items in the category. For example, condition ID 1000 could be called "New" in one category and "New with tags" in another. If an item is listed in two categories, the primary category controls the display name. Behind the scenes, eBay's search engine uses the ID (not the display name) to determine whether items are new, used, or refurbished. So, if you need to normalize the conditions across categories (such as to group items by condition), it may be easier to use the ID and then show the varying display names for reference. In condition histograms: If you search against a specific category and some items match based on their secondary category, the histogram only shows the display name if the secondary category supports the condition. (Condition IDs and names are dependent on the primary category.) However, the histogram shows the condition ID and item counts. This should only occur in a very small percent of results. As a workaround, you can fill in the missing name based on the "Item Condition IDs and Names" (link below) or based on the condition from an applicable item in the results. For example, suppose a seller lists a concert T-shirt in a clothing category with the condition "New without tags" (1500), and also in a music accessories secondary category (where "New without tags" isn't a recognized condition). If you specify the music accessories category in your request, the condition ID (1500) is shown in the histogram, but not the display name. However, the display name is shown within the items. Max length: 50. outputSelector: none (not controlled by outputSelector) See Item Condition IDs and Names for a list of display names and the typical meaning of each condition.
conditionHistogramContainer   .conditionHistogram.condition   .conditionId	int	Conditionally	The numeric ID (e.g., 1000) for the item condition. In item results, this is only returned when the seller listed the item with a condition ID. Some categories don't support or require condition IDs (e.g., most Antiques categories don't). If you Condition as a itemFilter, the response returns items with the correctly matching condition(s), even if conditionId is not returned. outputSelector: none (not controlled by outputSelector) See Item Condition IDs and Names for a list of display names and the typical meaning of each condition.
conditionHistogramContainer   .conditionHistogram.count	int	Conditionally	The number of items found that match the condition. Only counts items where the seller specified the condition by using item.conditionId. outputSelector: ConditionHistogram

Detail Controls

DetailLevel

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

outputSelector

The outputSelector input field gives you control over which call-specific output fields may be returned from your queries. outputSelector 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 outputSelector.)

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

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.

Retrieves a set of items based on the product type and value you provide. Product types can be ISBN, UPC, EAN, or ReferenceID (eBay Product Reference ID, or ePID).

Description

The user wants to search for a specific book by the eBay Product Reference ID number (ReferenceID).

Input

Like the other types of products on which you can make queries, the value of the associated product type (here, the ePID number) must be known before you can make the request.

Note: In the Finding Service, to specify an element parameter in a URL request, you must proceed the parameter with an "@" sign. For example, to specify a product ID type, use the following syntax:

&productId.@type=ReferenceID

Note: URL samples have been wrapped for readability. To run the samples, undo the line wrapping and insert your own SECURITY-APPNAME.

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://svcs.ebay.com/services/search/FindingService/v1?
   OPERATION-NAME=findItemsByProduct&
   SERVICE-VERSION=1.0.0&
   SECURITY-APPNAME=YourAppID&
   RESPONSE-DATA-FORMAT=XML&
   REST-PAYLOAD&
   paginationInput.entriesPerPage=2&
   productId.@type=ReferenceID&
   productId=53039031

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

XML format. Also available is the JSON equivalent.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByProductRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <productId type="ReferenceID">53039031</productId>
  <paginationInput>
    <entriesPerPage>2</entriesPerPage>
  </paginationInput>
</findItemsByProductRequest>

Output

XML format. Also available is the JSON equivalent.

<?xml version="1.0" encoding="utf-8"?>
<findItemsByProductResponse xmlns:ms="https://www.ebay.com/marketplace/services"
xmlns="http://www.ebay.com/marketplace/search/v1/services">
   <ack>Success</ack>
   <version>1.12.0</version>
   <timestamp>2015-09-10T00:54:12.443Z</timestamp>
   <searchResult count="2">
      <item>
         <itemId>1**********9</itemId>
         <title>The Little Mermaid DVD Disney Platinum Special Edition</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>617</categoryId>
            <categoryName>DVD, HD DVD & Blu-ray</categoryName>
         </primaryCategory>
         <galleryURL>
         https://thumbs2.ebaystatic.com/pict/1**************0_1.jpg</galleryURL>
         <viewItemURL>https://cgi.ebay.com/The-Little-Mermaid-DVD-Disney-Platinum-Special-
         Edition_W0QQitemZ1**********9QQcmdZViewItemQQptZUS_DVD_HD_DVD_Blu_ray?hash=
         item2a00eefcb1</viewItemURL>
         <productId type="ReferenceID">53039031</productId>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>19***</postalCode>
         <location>Philadelphia,PA,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
            <shippingType>Free</shippingType>
            <shipToLocations>US</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">15.5</currentPrice>
            <convertedCurrentPrice currencyId="USD">15.5</convertedCurrentPrice>
            <bidCount>4</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P0DT2H59M5S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2015-09-05T03:53:17.000Z</startTime>
            <endTime>2015-09-10T03:53:17.000Z</endTime>
            <listingType>Auction</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
      <item>
         <itemId>3**********4</itemId>
         <title>SEALED WALT DISNEY THE LITTLE MERMAID PLATINUM EDITION</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>617</categoryId>
            <categoryName>DVD, HD DVD & Blu-ray</categoryName>
         </primaryCategory>
         <galleryURL>
         https://thumbs1.ebaystatic.com/pict/3**************0_1.jpg</galleryURL>
         <viewItemURL>https://cgi.ebay.com/SEALED-WALT-DISNEY-THE-LITTLE-MERMAID-PLATINUM-
         EDITION_W0QQitemZ3**********4QQcmdZViewItemQQptZUS_DVD_HD_DVD_Blu_ray?hash=
         item483759611a</viewItemURL>
         <productId type="ReferenceID">53039031</productId>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <location>USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
            <shippingType>Free</shippingType>
            <shipToLocations>US</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">13.5</currentPrice>
            <convertedCurrentPrice currencyId="USD">13.5</convertedCurrentPrice>
            <bidCount>8</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P0DT23H42M34S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2015-09-04T00:36:46.000Z</startTime>
            <endTime>2015-09-11T00:36:46.000Z</endTime>
            <listingType>Auction</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
   </searchResult>
   <paginationOutput>
      <totalPages>50</totalPages>
      <totalEntries>99</totalEntries>
      <pageNumber>1</pageNumber>
      <entriesPerPage>2</entriesPerPage>
   </paginationOutput>
</findItemsByProductResponse>

Change History