findBestMatchItemDetailsBySeller

Deprecation Notice

Beginning January 1, 2013, the Best Match Item Details API will no longer be available. eBay sellers will continue to have access to information about listing performance via the eBay Listing Analytics tool. If your application currently supports the Best Match Item Details API, please direct your users to eBay's Listing Analytics tool instead.

This call takes a sellerUserName and a categoryId and returns information on the items listed by the specified seller. The call returns items in the category specified and all its child categories. If the sellerUserName is the same as the caller of the function, the service returns Best Match information for all the items in the category hierarchy.

The response contains the following information that sellers can use to rate the performance and Best Match placement of the returned items:

Best Match—Best Match data is returned for an item only if the item was listed by the authorized user of the BestMatchItemDetails call. Best Match data, among other things, includes an impression count range and a sales-per-impression value. The fields in the bestMatchData container list some of the values that eBay uses to determine the Best Match sorting order.
Item Ranking—The results for each item include itemRanking and itemRankWithinGroup fields. The values of these fields show where your item is placed in search results, and where it lands when compared to other items within the same group (the groups being Featured or Best Match).
Quantity Sold—Search results also return QuantitySold and QuantityAvailable fields. The QuantitySold value (when combined with the item impression counts) plays a roll in how the item is sorted by Best Match.

Sellers can use this call to view information on their own item listings, or they can view details of listings offered by another seller.

Controlling the Output

findBestMatchItemDetailsBySeller offers several ways to control response data. Use itemFilter fields to limit the response by filtering on specific item properties. Use paginationInput fields to specify the number of items to return and the page to view.

The following sections give more information on how to control the response data:

Controlling the Items Returned with Item Filters
Specifying the Items Per Page
Returning Featured Items
Specifying the eBay Site

Controlling the Items Returned with Item Filters

Filters give you control over search results by narrowing the range of items returned. The itemFilter container uses name/value pairs to describe specific filters. You can specify filters for a variety of properties, including the item condition, number of bids, price range, listing type, and so on. All item filters are optional input parameters.

For example, the following filters specify that items in the result must be between $45 and $60 US Dollars:

<itemFilter>
  <Name>MinPrice</Name>
  <Value>45.00</Value>
  <ParamName>Currency</Name>
  <ParamValue>USD</Value>
</itemFilter>
<itemFilter>
  <Name>MaxPrice</Name>
  <Value>60.00</Value>
  <ParamName>Currency</Name>
  <ParamValue>USD</Value>
</itemFilter>

For details on how to use item filters, see Refining a Search with Item Filters in the User Guide. The ItemFilterType document has information about the allowed values, usage rules, and dependencies of the different filters.

Specifying the Items Per Page

The entriesPerPage and pageNumber fields in the inputPaginagion container control the number of items to return per response and the page to return from the result set. In the response, fields in the paginationOutput container provides details on the total size of the response set and the page returned. To view the entire result set, iterate through the pages by incrementing the pageNumber value in separate queries to findBestMatchItemDetailsBySeller.

Returning Featured Items

By default, findBestMatchItemDetailsBySeller calls return Featured items in the response. If you want to view only Best Match items, set ignoreFeatured to true.

Specifying the eBay Site

The X-EBAY-SOA-GLOBAL-ID HTTP header specifies the eBay site to use for searches. When specifying a global ID (e.g., EBAY-DE for the eBay Germany site), the search response contains only items available on the site specified. If you do not specify a global ID, eBay uses the US site (EBAY-US) by default.

For more information about HTTP headers, see HTTP Headers in Making a BestMatchItemDetails API Call.

findBestMatchItemDetailsBySeller Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

findBestMatchItemDetailsBySeller Output

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

<?xml version="1.0" encoding="utf-8"?>
<findBestMatchItemDetailsBySellerResponse xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <!-- Call-specific Output Fields -->
  <paginationOutput> PaginationOutput
    <entriesPerPage> int </entriesPerPage>
    <pageNumber> int </pageNumber>
    <totalEntries> int </totalEntries>
    <totalPages> int </totalPages>
  </paginationOutput>
  <!-- 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>
  <searchResult count="int"> BestMatchSearchResult
    <searchItemGroup itemGroup="string" itemGroupName="string" itemGroupCount="int"> SearchItemGroup
      <item> BestMatchSearchItem (SearchItem)
        <autoPay> boolean </autoPay>
        <bestMatchData> BestMatchData
          <freeShipping> boolean </freeShipping>
          <impressionCountRange> LongRange
            <max> long </max>
            <min> long </min>
          </impressionCountRange>
          <salesCount> int </salesCount>
          <salesPerImpression> double </salesPerImpression>
          <salesPerViewItem> double </salesPerViewItem>
          <viewItemCount> int </viewItemCount>
          <viewItemPerImpression> double </viewItemPerImpression>
          <watchCount> int </watchCount>
        </bestMatchData>
        <charityId> string </charityId>
        <country> token </country>
        <galleryPlusPictureURL> anyURI </galleryPlusPictureURL>
        <!-- ... more galleryPlusPictureURL values allowed here ... -->
        <galleryURL> anyURI </galleryURL>
        <globalId> token </globalId>
        <itemId> string </itemId>
        <itemRank> int </itemRank>
        <itemRankWithinGroup> int </itemRankWithinGroup>
        <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 ... -->
        <postalCode> string </postalCode>
        <primaryCategory> Category
          <categoryId> string </categoryId>
          <categoryName> string </categoryName>
        </primaryCategory>
        <productId type="string"> ProductId (string) </productId>
        <quantityAvailable> int </quantityAvailable>
        <quantitySold> int </quantitySold>
        <secondaryCategory> Category
          <categoryId> string </categoryId>
          <categoryName> string </categoryName>
        </secondaryCategory>
        <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
          <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>
        <viewItemURL> anyURI </viewItemURL>
      </item>
      <!-- ... more item nodes allowed here ... -->
    </searchItemGroup>
    <!-- ... more searchItemGroup nodes allowed here ... -->
    <totalEntries> int </totalEntries>
  </searchResult>
  <timestamp> dateTime </timestamp>
  <version> string </version>
</findBestMatchItemDetailsBySellerResponse>

Return Value	Type	Occurrence	Meaning

Call-specific Output Fields [Jump to standard fields]

paginationOutput	PaginationOutput	Always	Indicates the pagination of the result set. Child elements indicate the page number that is returned, the maximum number of items returned in the page (as specified), the total number of pages that can be returned, and the total number of listings that match the search criteria.
paginationOutput .entriesPerPage	int	Always	The maximum number of items that can be returned in the response. This number is always equal to the value input for paginationInput.entriesPerPage. The end of the result set has been reached if the number specified for entriesPerPage is greater than the number of items found on the specified pageNumber. In this case, there will be fewer items returned than the number specified in entriesPerPage. This can be determined by comparing the entriesPerPage value with the value returned in the count attribute for the searchResult field.
paginationOutput.pageNumber	int	Always	The subset of item data returned in the current response. Search results are divided into sets, or "pages," of item data. The number of pages is equal to the total number of items matching the search criteria divided by the value specified for entriesPerPage in the request. The response for a request contains one "page" of item data. This returned value indicates the page number of item data returned (a subset of the complete result set). If this field contains 1, the response contains the first page of item data (the default). If the value returned in totalEntries is less than the value for entriesPerPage, pageNumber returns 1 and the response contains the entire result set. The value of pageNumber is normally equal to the value input for paginationInput.pageNumber. However, if the number input for pageNumber is greater than the total possible pages of output, eBay returns the last page of item data in the result set, and the value for pageNumber is set to the respective (last) page number.
paginationOutput.totalEntries	int	Always	The total number of items found that match the search criteria in your request. Depending on the input value for entriesPerPage, the response might include only a portion (a page) of the entire result set. A value of "0" is returned if eBay does not find any items that match the search criteria.
paginationOutput.totalPages	int	Always	The total number of pages of data that could be returned by repeated search requests. Note that if you modify the value of inputPagination.entriesPerPage in a request, the value output for totalPages will change. A value of "0" is returned if eBay does not find any items that match the search criteria.

Standard Output Fields

ack	AckValue	Always	Indicates whether or not the request was successful, or if errors or warnings were generated during the processing of the request. Applicable values: • Failure eBay encountered a fatal error during the processing of the request, causing the request to fail. When a serious application-level error occurs, the error is returned instead of the business data. • PartialFailure eBay successfully processed the request, but one or more non-fatal errors occurred during the processing. For best results, requests should return without warning messages. Inspect the message details and resolve any problems before resubmitting the request. • Success eBay successfully processed the request and the business data is returned in the response. Note that it is possible for a response to return Success, but still not contain the expected data in the result. • Warning The request was successfully processed, but eBay encountered a non-fatal error during the processing. For best results, requests should return without warnings. Inspect the warning details and resolve the problem before resubmitting the request.
errorMessage	ErrorMessage	Conditionally	Description of an error or warning that occurred when eBay processed the request. Not returned if the ack value is Success.
errorMessage.error	ErrorData	Conditionally, repeatable: [0..*]	Details about a single error.
errorMessage.error.category	ErrorCategory	Conditionally	There are three categories of errors: Request errors, Application errors, and System errors. Applicable values: • Application An error occurred due to a problem with the request, with the most likely source being the application sending the request. For example, the request is missing a required data element or it contains an invalid field. The problem must be corrected before the request can be resent. Inspect the error message to find the cause of the problem. If the problem is due to an application error, modify the application and resend the request. If the error is due to invalid data, the source of the data must be corrected before you resend the resend request to eBay. • Request An error occurred due to a problem with the request, with the most likely source being missing or invalid data in the request. The problem must be corrected before the request can be retried. Inspect the error message to find the cause of the problem. If the problem is a result of end-user data, alert the end-user to the problem and provide the means for them to correct the problem. Once the problem is resolved, resend the request to eBay. • System Indicates that an error has occurred on the eBay system side. For example, a database or server could be down. Inspect the error message to find the cause of the problem. If the problem is on the eBay side, 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.
errorMessage.error.domain	string	Conditionally	Name of the domain in which the error occurred. domain values: Marketplace A business or validation error occurred in the Merchandising Service. SOA An exception occurred in the Service Oriented Architecture (SOA) framework.
errorMessage.error.errorId	long	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.
errorMessage.error.exceptionId	token	Conditionally	Unique identifier for an exception associated with an error.
errorMessage.error.message	string	Conditionally	A detailed description of the condition that caused in the error.
errorMessage.error.parameter	ErrorParameter (string)	Conditionally, repeatable: [0..*]	Various 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.
errorMessage.error.parameter [ attribute name ]	string	Conditionally	The name of the input parameter returned with the error. Inspecting the parameter (or its input value) will often aid in understanding the cause of the error. Not all error messages contain this value.
errorMessage.error.severity	ErrorSeverity	Conditionally	Indicates whether the reported problem is fatal (an error) or is less severe (a warning). Review the error message details for information on the cause. If the request fails and the application is the source of the error (for example, a required element is missing), update the application before you retry the request. If the problem is due to incorrect user data, 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, re-send the request to eBay. If the source of the problem is on eBay's side, you can retry the request a reasonable number of times (eBay recommends you try the request twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, you can resend the request in its original form. If a warning occurs, warning information is returned in addition to the business data. Normally, you do not need to resend the request (as the original request was successful). However, depending on the cause of the warning, you might need to contact the end user, or eBay, to effect a long term solution to the problem. Applicable values: • Error eBay encountered a fatal error during the processing of the request, causing the request to fail. When eBay encounters an error, it returns error data instead of the requested business data. Inspect the error details and resolve the problem before resubmitting the request. • Warning The request was successfully processed, but eBay encountered a non-fatal error during the processing that could affect the data returned. For example, eBay might have changed the value of an input field. In this case, eBay returns a successful response, but it also returns a warning. For best results, requests should return without warnings. Inspect the warning details and resolve the problem before resubmitting the request.
errorMessage.error.subdomain	string	Conditionally	Name of the subdomain in which the error occurred. subdomain values: Search The error is specific to the search services. MarketplaceCommon The error is common to all Marketplace services.
searchResult	BestMatchSearchResult	Always	Container for the list of returned items. The items are sorted according to where they appear on search page: in the Featured or Search Result (BestMatch) group, or under Condition.
searchResult [ attribute count ]	int	Conditionally	Total number of items returned. Not returned if no items match the search query (totalEntries=0). This value is usually equal to the input value for entriesPerPage, unless the query matches fewer items than the value specified for entriesPerPage.
searchResult.searchItemGroup	SearchItemGroup	Always, repeatable: [1..*]	Container for items that match the associated itemGroupName parameter. For search and non-media PDP, it contains featured and mixed result-set groups. For media PDP, it contains item condition groups: Brand New, Like New, Very Good, Good and Acceptable.
searchResult.searchItemGroup [ attribute itemGroup ]	string	Always	Criteria according to which the items in the container are grouped. Within searchItemGroup elements, the possible values are Placement (which means placement in the result set, under the Featured results or under the Best Match results) and Condition (for media products). Within itemGroupSummary elements, the value is always Format.
searchResult.searchItemGroup [ attribute itemGroupName ]	string	Always	Name of the group to which the group of items belongs. Possible values are BestMatch and featured. Also, for Media products, the itemGroupName can be the product condition: Brand New, Like New, Very Good, Good, and Acceptable.
searchResult.searchItemGroup [ attribute itemGroupCount ]	int	Always	Number of items in the group.
searchResult.searchItemGroup .item	BestMatchSearchItem (SearchItem)	Always, repeatable: [1..*]	Container for the details pertaining to a single item listing.
searchResult.searchItemGroup .item.autoPay	boolean	Always	If true, the seller requests immediate payment for the item. If false (or not specified), immediate payment is not requested. If true, it does not indicate that the item is still a candidate for purchase via immediate payment, however it does indicate the original status of the item listing. Only applicable to items listed on PayPal-enabled sites and in categories that support immediate payment (see AutoPayEnabled in GetCategories). In addition, the seller must have a Premier or Business PayPal account (see PayPalAccountType in GetUser) and they must accept PayPal as a payment method (see item.paymentMethod). See the eBay Web Services guide section on Requiring Immediate Payment for additional requirements and dependencies. Also see the section on working with the eBay Motors site for additional rules. Not applicable to Half.com.
searchResult.searchItemGroup .item.bestMatchData	BestMatchData	Conditionally	Container for the best match data for the item. This data is returned only for items that belong to the authorized caller; the service does not return Best Match data for items that were not listed by the caller of the function.
searchResult.searchItemGroup .item.bestMatchData .freeShipping	boolean	Conditionally	If true, the item is considered a free shipping item by BestMatch.
searchResult.searchItemGroup .item.bestMatchData .impressionCountRange	LongRange	Conditionally	Total number of times the item surfaced on a search results page. The impression count is returned as a range.
searchResult.searchItemGroup .item.bestMatchData .impressionCountRange.max	long	Conditionally	Maximum impression range value.
searchResult.searchItemGroup .item.bestMatchData .impressionCountRange.min	long	Conditionally	Minimum impression range value.
searchResult.searchItemGroup .item.bestMatchData.salesCount	int	Conditionally	Number of item sales. Note that a single sale can include one or more items.
searchResult.searchItemGroup .item.bestMatchData .salesPerImpression	double	Conditionally	Ratio of sale transactions to the mid-point (between the minimum and maximum number) of the impression range. Note that the number of items sold can exceed the number of transactions (sales) if a single sale has an item quantity greater than one. An "impression" is any time a buyer sees a search results page that includes the listing. Impression counts can be greater than unique item views. Note that salesPerImpression impacts Best Match results for only Fixed Price items.
searchResult.searchItemGroup .item.bestMatchData .salesPerViewItem	double	Conditionally	Ratio of sales to unique views of the item.
searchResult.searchItemGroup .item.bestMatchData .viewItemCount	int	Conditionally	Number of unique item views.
searchResult.searchItemGroup .item.bestMatchData .viewItemPerImpression	double	Conditionally	Ratio of unique item-views to the mid-point of the impression range. An "impression" is any time a buyer sees a search results page that includes the listing whereas "unique views" counts each user only once.
searchResult.searchItemGroup .item.bestMatchData.watchCount	int	Conditionally	Number of watches placed on the item.
searchResult.searchItemGroup .item.charityId	string	Conditionally	A unique identification number assigned by eBay to registered nonprofit charity organizations. Not returned if the item is not listed as a charity item.
searchResult.searchItemGroup .item.country	token	Always	Two-letter ISO 3166 country code to indicate the country where the item is located. For English names that correspond to each code (e.g., KY="Cayman Islands"), see the ISO site: http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html.
searchResult.searchItemGroup .item.galleryPlusPictureURL	anyURI	Conditionally, repeatable: [0..*]	URL for the Gallery Plus image. The size of Gallery Plus images (up to 400 x 400 pixels) is bigger than the size of standard gallery images. In site search results, you can view the Gallery Plus image by hovering over or clicking the Enlarge link or magifying glass icon. The image uses one of the following graphics formats: JPEG, BMP, TIFF, or GIF. This field is only returned when the seller has opted for the Gallery Plus option for the given item.
searchResult.searchItemGroup .item.galleryURL	anyURI	Conditionally	URL for the picture used for the Gallery thumbnail, if any. The image uses one of the following graphics formats: JPEG, BMP, TIF, or GIF. Only returned if the seller chose to show a gallery image.
searchResult.searchItemGroup .item.globalId	token	Always	A token that represents the eBay site on which the item was originally listed. For example, if the item was listed on the eBay US site, the value is US. If item was listed on the eBay Germany site, the value is DE. For a list of possible enumeration values and how they map to eBay sites, see Global ID Values. Where the item was listed can affect the values of converted (localized) prices. This occurs when the site from which your request is sent is different from the site on which the item was listed.
searchResult.searchItemGroup .item.itemId	string	Always	An identification number that uniquely identifies a listed item. eBay generates this ID when an item is listed and the ID is unique across all eBay sites.
searchResult.searchItemGroup .item.itemRank	int	Always	Absolute rank of the item, across the groups, in relation to all returned items.
searchResult.searchItemGroup .item.itemRankWithinGroup	int	Always	Rank of the item in relation to the other returned items in the same group. Item groups are Featured and Best Match. For media items, groups can be Brand New, Like New, Very Good, Good, and Acceptable.
searchResult.searchItemGroup .item.listingInfo	ListingInfo	Always	Container for listing information related to the item. The information includes the item's listing format (online auction, fixed price, and so on), if Buy It Now is enabled, and more.
searchResult.searchItemGroup .item.listingInfo .bestOfferEnabled	boolean	Always	Shows whether or not the seller will accept a Best Offer for the associated item. Best Offer allows a buyer to make a lower-priced binding offer on a fixed price item. Buyers cannot see how many offers have been made (only the seller can see this information). Buyers must use the eBay Web site to make a Best Offer.
searchResult.searchItemGroup .item.listingInfo .buyItNowAvailable	boolean	Always	Used with competitive-bid auctions, the associated item includes a Buy It Now option if this value returns true. Buy It Now lets a user purchase the item at a fixed price, effectively ending the auction. On most sites, the Buy It Now option is removed (and this value returns false) once a valid bid is made on the associated item (a valid bid could be a bid above the reserve price).
searchResult.searchItemGroup .item.listingInfo .buyItNowPrice	Amount (double)	Always	The Buy It Now Price of the item (if any), in the currency of the site on which the item was listed. You can use this field to determine if the item was originally listed with Buy It Now, even if the Buy It Now option is no longer available for the item. Only returned if an item was listed with Buy It Now.
searchResult.searchItemGroup .item.listingInfo .buyItNowPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
searchResult.searchItemGroup .item.listingInfo .convertedBuyItNowPrice	Amount (double)	Always	The listing's Buy It Now Price (if any), converted into the currency of the site to which you sent your search request. For active items, refresh this value every 24 hours to pick up possible changes in conversion rates. Price fields are returned as doubles, and not necessarily in the traditional monetary format of the site's country. For example, a US Dollar value might be returned as 3.880001 instead of 3.88. Only returned if an item was listed with Buy It Now.
searchResult.searchItemGroup .item.listingInfo .convertedBuyItNowPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
searchResult.searchItemGroup .item.listingInfo.endTime	dateTime	Always	Time stamp specifying when the listing is scheduled to end, or the actual end time if the item listing has ended. This value is returned in GMT, the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about the time format, and for details on converting to and from the GMT time zone. Note: For items that are "Good Till Canceled," this value is 5 minutes later than the actual end time of the item. This difference in time is intended to facilitate the renewal of these items' end times (which occurs every 30 days).
searchResult.searchItemGroup .item.listingInfo.gift	boolean	Always	If true, a small gift icon displays next the listing's title in search and browse pages.
searchResult.searchItemGroup .item.listingInfo.listingType	token	Always	The format of the listing, such as online auction, fixed price, or advertisement. listingType values: AdFormat Advertisement to solicit inquiries on listings such as real estate. Permits no bidding on the item, service, or property. To express interest, a buyer fills out a contact form that eBay forwards to the seller as a lead. This format does not enable buyers and sellers to transact online through eBay and eBay Feedback is not available for AdFormat listings. Auction Competitive-bidding online auction format. Buyers engage in competitive bidding, although Buy It Now may be offered as long as no valid bids have been placed. Online auctions are listed on eBay.com; they can also be listed in a seller's eBay Store if the seller is a Store owner. AuctionWithBIN Same as Auction format, but Buy It Now is enabled. AuctionWithBIN changes to Auction if a valid bid has been placed on the item. Valid bids include bids that are equal to or above any specified reserve price. Classified Classified Ads connect buyers and sellers, who then complete the sale outside of eBay. This format does not enable buyers and sellers to transact online through eBay and eBay Feedback is not available for these listing types. FixedPrice A fixed-price listing. Auction-style bidding is not enabled. On some sites, this auction format is also known as "Buy It Now Only" (do not confuse this with the Buy It Now option available on competitive-bidding auctions). Fixed-price listings appear on eBay.com and they can be listed in a seller's eBay Store (if the seller is a Store owner). StoreInventory A fixed-price format for eBay Store sellers. Store Inventory listings appear after other listings in regular search and browse pages on eBay. Store items have a lower Insertion Fee and longer listing durations. This selling type can only be specified by sellers who have an eBay Store. Store Inventory listings are listed on eBay.com as well as in the seller's eBay Store.
searchResult.searchItemGroup .item.listingInfo.startTime	dateTime	Always	Time stamp that eBay recorded as the moment the listing was made available. This value is returned in GMT, the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about the time format and for details on converting to and from the GMT time zone.
searchResult.searchItemGroup .item.location	string	Always	Physical location of the item, as specified by the seller. (This gives a general indication of from where the item will be shipped or delivered.)
searchResult.searchItemGroup .item.paymentMethod	token	Always, repeatable: [1..*]	Identifies the payment method(s) the seller will accept from the buyer. An example is PayPal. Note: If the seller accepts only PayPal, the buyer can still pay with a credit card. PayPal supports major credit cards. Payment methods are not applicable to eBay Real Estate advertisement listings or other Classified Ad format listings.
searchResult.searchItemGroup .item.postalCode	string	Conditionally	The postal code of where the item is located. Not returned if seller did not specify their postal code.
searchResult.searchItemGroup .item.primaryCategory	Category	Always	Container for the numeric ID and name of the first (or only) category in which the item is listed. Note that listings can appear in more than a single category.
searchResult.searchItemGroup .item.primaryCategory .categoryId	string	Always	The unique ID of a category on the specified eBay site.
searchResult.searchItemGroup .item.primaryCategory .categoryName	string	Always	Display name of a category as it appears on the eBay Web site. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks).
searchResult.searchItemGroup .item.productId	ProductId (string)	Conditionally	Product ID type and product ID code if the item is a catalogue item. Not returned if the item is not listed as a product.
searchResult.searchItemGroup .item.productId [ attribute type ]	string	Conditionally	Specifies or returns the product type and product ID. productId types: ReferenceID The global reference ID (ePID) for an eBay catalog product. A reference ID is a fixed reference to a product, regardless of version. Use FindProducts in the Shopping API to determine valid ePID values that you can use as input to findItemsByProduct. Each product in the response includes its reference ID. ISBN ISBN-10 or ISBN-13 value for books. (The string length of ProductID indicates whether the ID is 10 or 13 characters.) If you know a book's ISBN, you can use this instead of the eBay Reference ID to search for that book. Max length of corresponding value: 13 UPC UPC value for products in Music (e.g., CDs), DVDs & Movies, and Video Games categories (or domains). If you know a product's UPC, you can use this instead of the eBay Reference ID to search for that product. Max length of corresponding value: 12 EAN EAN value for books. (This is used more commonly 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. Max length of corresponding value: 13 For example: To search using an ISBN, specify productID.type=ISBN and set productID.value to an ISBN value. To search using an eBay Product Reference ID, specify productID.type=ReferenceID and set productID.value to an eBay Product Reference ID (ePID) value. If you do not know the eBay Product Reference ID of a product, use the Shopping FindProducts call to retrieve the desired ePID value.
searchResult.searchItemGroup .item.quantityAvailable	int	Always	Quantity of available items in the listing.
searchResult.searchItemGroup .item.quantitySold	int	Always	Number of listing items sold.
searchResult.searchItemGroup .item.secondaryCategory	Category	Conditionally	Container for the numeric ID and name of the second category in which the item is listed, if the seller listed in a secondary category.
searchResult.searchItemGroup .item.secondaryCategory .categoryId	string	Conditionally	The unique ID of a category on the specified eBay site.
searchResult.searchItemGroup .item.secondaryCategory .categoryName	string	Conditionally	Display name of a category as it appears on the eBay Web site. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks).
searchResult.searchItemGroup .item.sellingStatus	SellingStatus	Always	Signifies the listing's selling status in eBay's processing workflow.
searchResult.searchItemGroup .item.sellingStatus.bidCount	int	Conditionally	The number of bids that have been placed on the item. Returned only if the selling format is an auction.
searchResult.searchItemGroup .item.sellingStatus .convertedCurrentPrice	Amount (double)	Always	The listing's current price converted to the currency of the site from which the request is sent (the request's globalId value).
searchResult.searchItemGroup .item.sellingStatus .convertedCurrentPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
searchResult.searchItemGroup .item.sellingStatus .currentPrice	Amount (double)	Always	The current price of the item given in the currency of the site on which the item is listed. That is, currentPrice is returned in the original listing currency. For competitive-bid item listings, currentPrice is the current minimum bid price if the listing has no bids, or the current high bid if the listing has bids. A Buy It Now price has no effect on currentPrice. For Basic Fixed-Price (FixedPrice), Store Inventory (StoreInventory), and Ad Format (AdFormat) listings, currentPrice is the current fixed price.
searchResult.searchItemGroup .item.sellingStatus .currentPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
searchResult.searchItemGroup .item.sellingStatus .sellingState	token	Always	Specifies the listing's status in eBay's processing workflow. If an item's EndTime is in the past, but there are no details about the buyer or high bidder (and the user is not anonymous), you can use sellingState information to determine whether eBay has finished processing the listing. sellingState values: Active The listing is still live. It is also possible that the auction has recently ended, but eBay has not completed the final processing (e.g., the high bidder is still being determined). Canceled The listing has been canceled by either the seller or eBay. Ended The listing has ended and eBay has completed the processing of the sale (if any).
searchResult.searchItemGroup .item.sellingStatus.timeLeft	duration	Always	Time left before the listing ends. The duration is represented in the ISO 8601 duration format (PnYnMnDTnHnMnS). For listings that have ended, the time left is PT0S (zero seconds). See the "duration" type for information about this time format.
searchResult.searchItemGroup .item.shippingInfo	ShippingInfo	Always	Container for information about the listing's shipping details.
searchResult.searchItemGroup .item.shippingInfo .shippingServiceCost	Amount (double)	Conditionally	The basic shipping cost of the item. Not returned if the shipping method is calculated or free.
searchResult.searchItemGroup .item.shippingInfo .shippingServiceCost [ attribute currencyId ]	string	Conditionally	Currency in which the monetary amount is specified. For a list of currencyId enumeration values, see currencyId Values.
searchResult.searchItemGroup .item.shippingInfo .shippingType	token	Always	The shipping method that was used for determining the cost of shipping. For example: flat rate, calculated, or free. The seller specifies the available shipping services when they list the item. shippingType values: Calculated The calculated shipping model: The posted cost of shipping is based on the buyer-selected shipping service, chosen by the buyer from the different shipping services offered by the seller. The shipping costs are calculated by eBay and the shipping carrier, based on the buyer's address. Any packaging and handling costs established by the seller are automatically rolled into the total. CalculatedDomesticFlatInternational The seller specified one or more calculated domestic shipping services and one or more flat international shipping services. Flat The flat-rate shipping model: The seller establishes the cost of shipping and any shipping insurance, regardless of what any buyer-selected shipping service might charge the seller. FlatDomesticCalculatedInternational The seller specified one or more flat domestic shipping services and one or more calculated international shipping services. Free Free is used when the seller has declared that shipping is free for the buyer. FreePickup No shipping available, the buyer must pick up the item from the seller. Freight The freight shipping model: the cost of shipping is determined by a third party, FreightQuote.com, based on the buyer's address (postal code). FreightFlat The flat rate shipping model: the seller establishes the cost of freight shipping and freight insurance, regardless of what any buyer-selected shipping service might charge the seller. NotSpecified The seller did not specify the shipping type.
searchResult.searchItemGroup .item.shippingInfo .shipToLocations	string	Conditionally, repeatable: [0..*]	An international location or region to which the seller is willing to ship the item. Returned only for items that have shipToLocations specified. For a complete list of shipping locations, see shipToLocations.
searchResult.searchItemGroup .item.storeInfo	Storefront	Conditionally	Container for information about the eBay store in which the item was listed. Not returned if the item is not listed in an eBay store.
searchResult.searchItemGroup .item.storeInfo.storeName	string	Conditionally	The name of the seller's eBay Store.
searchResult.searchItemGroup .item.storeInfo.storeURL	anyURI	Conditionally	The URL of the eBay Store page.
searchResult.searchItemGroup .item.subtitle	string	Conditionally	Subtitle of the item. Only returned if the seller included a subtitle with the listing.
searchResult.searchItemGroup .item.title	string	Always	Name of the item listing as it appears in search and browse results.
searchResult.searchItemGroup .item.viewItemURL	anyURI	Always	The URL to view this listing on eBay. This URL is optimized to support natural search. That is, this URL is designed to make items on eBay easier to find via popular Internet search engines. Specifically, the URL specifies the item title and it is optimized for natural search: " _W0QQ" is like "?" (question mark), "QQ" is like "&" (ampersand), and "Z" is like "=" (equals sign). Do not modify the returned URL syntax in your application. For example, eBay won't recognize the URL if you change QQ to ?. In the Sandbox environment and on the Hong Kong site (site ID 201), the data returned in this field is a standard ViewItem URL, rather than the ViewItem URL for Natural Search that is normally returned in the Production environment.
searchResult.totalEntries	int	Conditionally	Total number of items in all item groups that match the query.
timestamp	dateTime	Always	This value represents the date and time when eBay processed the request. This value is returned in GMT, the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about the time format, and for details on converting to and from the GMT time zone.
version	string	Always	The release version that eBay used to process the request. Developer Technical Support may ask you for the version value if you work with them to troubleshoot issues. Note: The version in use is normally the latest release version, as specified in the release notes. Note that eBay releases the API to international sites about a week after the API version is released to the US site.

findBestMatchItemDetailsBySeller Detail Controls

Detail Control: DetailLevel

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

findBestMatchItemDetailsBySeller Samples

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

Note: Some data in these samples might no longer be active. If necessary, you can substitute current data in your requests.

Sample: Basic

Mimimal findBestMatchItemDetailsBySeller call.

Description

This call returns the items in a category hierarchy that were listed by a specific seller. If the specified seller matches the supplied authorization token, Best Match data is returned for each of the returned items.

Input

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<findBestMatchItemDetailsBySellerRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <sellerUserName>MegaSeller</sellerUserName>
  <categoryId>267</categoryId>
</findBestMatchItemDetailsBySellerRequest>

Output

XML format. Also available is the .txt version of this XML.

<findBestMatchItemDetailsBySellerResponse xmlns:ms="http://www.ebay.com/marketplace/services"
    xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <ack>Success</ack>
  <version>1.1.0</version>
  <timestamp>2009-10-22T00:54:27.700Z</timestamp>
  <searchResult count="3">
    <searchItemGroup itemGroupCount="3" itemGroupName="BestMatch" itemGroup="Placement">
      <item>
        <itemId>200001018787</itemId>
        <title>Harry Potter and the Goblet of Fire</title>
        <globalId>EBAY-US</globalId>
        <primaryCategory>
          <categoryId>279</categoryId>
          <categoryName>Children & Young Adults</categoryName>
        </primaryCategory>
        <secondaryCategory>
          <categoryId>377</categoryId>
          <categoryName>Fiction & Literature</categoryName>
        </secondaryCategory>
        <galleryURL>http://thumbs2.qa.ebaystatic.com/pict/2000010187878080_1.jpg</galleryURL>
        <viewItemURL>http://cgi.qa.ebay.com/Harry-Potter-and-the-Goblet-of-Fire_
            W0QQitemZ200001018787QQcmdZViewItemQQptZCDC_QA_US_PT_Books</viewItemURL>
        <paymentMethod>PayPal</paymentMethod>
        <autoPay>false</autoPay>
        <postalCode>95125</postalCode>
        <location>San Jose,CA,USA</location>
        <country>US</country>
        <shippingInfo>
          <shippingServiceCost currencyId="USD">1.0</shippingServiceCost>
          <shippingType>Flat</shippingType>
          <shipToLocations>US</shipToLocations>
        </shippingInfo>
        <sellingStatus>
          <currentPrice currencyId="USD">1.0</currentPrice>
          <convertedCurrentPrice currencyId="USD">1.0</convertedCurrentPrice>
          <bidCount>0</bidCount>
          <sellingState>Active</sellingState>
          <timeLeft>P0DT17H34M19S</timeLeft>
        </sellingStatus>
        <listingInfo>
          <bestOfferEnabled>false</bestOfferEnabled>
          <buyItNowAvailable>false</buyItNowAvailable>
          <startTime>2009-10-21T18:28:46.000Z</startTime>
          <endTime>2009-10-28T18:28:46.000Z</endTime>
          <listingType>Auction</listingType>
          <gift>false</gift>
        </listingInfo>
        <itemRank>1</itemRank>
        <itemRankWithinGroup>1</itemRankWithinGroup>
        <quantityAvailable>1</quantityAvailable>
        <quantitySold>0</quantitySold>
        <bestMatchData>
          <freeShipping>false</freeShipping>
          <impressionCountRange>
            <min>1</min>
            <max>50</max>
          </impressionCountRange>
          <salesCount>0</salesCount>
          <viewItemCount>6</viewItemCount>
          <watchCount>1</watchCount>
          <salesPerImpression>0.0</salesPerImpression>
          <salesPerViewItem>0.0</salesPerViewItem>
          <viewItemPerImpression>0.16228</viewItemPerImpression>
        </bestMatchData>
      </item>
      <item>
        <itemId>200001018789</itemId>
        <title>Harry Potter The Complete Series by J. K. Rowling</title>
        <globalId>EBAY-US</globalId>
        <subtitle>Brand new, Fast shipping</subtitle>
        <primaryCategory>
          <categoryId>279</categoryId>
          <categoryName>Children & Young Adults</categoryName>
        </primaryCategory>
        <galleryURL>http://thumbs.ebaystatic.com/pict/1903376298668080_1.jpg</galleryURL>
        <viewItemURL>http://cgi.ebay.com/Harry-Potter-The-Complete-Series-by-J-K-Rowling_
            W0QQitemZ190337629866QQcmdZViewItemQQptZUS_Childrens_Books?
            hash=item2c5101beaa</viewItemURL>
        <productId type="ReferenceID">71683485</productId>
        <paymentMethod>PayPal</paymentMethod>
        <autoPay>false</autoPay>
        <postalCode>95125</postalCode>
        <location>San Jose,CA,USA</location>
        <country>US</country>
        <shippingInfo>
          <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
          <shippingType>Free</shippingType>
          <shipToLocations>US</shipToLocations>
        </shippingInfo>
        <sellingStatus>
          <currentPrice currencyId="USD">38.0</currentPrice>
          <convertedCurrentPrice currencyId="USD">38.0</convertedCurrentPrice>
          <sellingState>Active</sellingState>
          <timeLeft>P26DT0H36M27S</timeLeft>
        </sellingStatus>
        <listingInfo>
          <bestOfferEnabled>false</bestOfferEnabled>
          <buyItNowAvailable>false</buyItNowAvailable>
          <startTime>2009-09-21T18:25:02.000Z</startTime>
          <endTime>2009-10-21T18:25:02.000Z</endTime>
          <listingType>FixedPrice</listingType>
          <gift>false</gift>
        </listingInfo>
        <itemRank>2</itemRank>
        <itemRankWithinGroup>2</itemRankWithinGroup>
        <quantityAvailable>86</quantityAvailable>
        <quantitySold>14</quantitySold>
        <bestMatchData>
          <freeShipping>true</freeShipping>
          <impressionCountRange>
            <min>501</min>
            <max>750</max>
          </impressionCountRange>
          <salesCount>0</salesCount>
          <viewItemCount>14</viewItemCount>
          <watchCount>7</watchCount>
          <salesPerImpression>0.0</salesPerImpression>
          <salesPerViewItem>0.0</salesPerViewItem>
          <viewItemPerImpression>0.01372</viewItemPerImpression>
        </bestMatchData>
      </item>
      <item>
        <itemId>200001018791</itemId>
        <title>Harry Potter and the Philosopher's Stone Japanese</title>
        <globalId>EBAY-US</globalId>
        <subtitle>FREE SHIPPING</subtitle>
        <primaryCategory>
          <categoryId>377</categoryId>
          <categoryName>Fiction & Literature</categoryName>
        </primaryCategory>
        <galleryURL>http://thumbs.ebaystatic.com/pict/1503754637088080_2.jpg</galleryURL>
        <viewItemURL>http://cgi.ebay.com/Harry-Potter-and-the-Philosophers-Stone-Japanese_
            W0QQitemZ150375463708QQcmdZViewItemQQptZUS_Fiction_Books?
            hash=item2303137b1c</viewItemURL>
        <paymentMethod>CashOnPickup</paymentMethod>
        <paymentMethod>PayPal</paymentMethod>
        <autoPay>false</autoPay>
        <postalCode>95125</postalCode>
        <location>San Jose,CA,USA</location>
        <country>US</country>
        <shippingInfo>
          <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
          <shippingType>Free</shippingType>
          <shipToLocations>US</shipToLocations>
        </shippingInfo>
        <sellingStatus>
          <currentPrice currencyId="USD">9.99</currentPrice>
          <convertedCurrentPrice currencyId="USD">9.99</convertedCurrentPrice>
          <bidCount>1</bidCount>
          <sellingState>Active</sellingState>
          <timeLeft>P0DT3H26M40S</timeLeft>
        </sellingStatus>
        <listingInfo>
          <bestOfferEnabled>false</bestOfferEnabled>
          <buyItNowAvailable>false</buyItNowAvailable>
          <startTime>2009-10-20T21:15:15.000Z</startTime>
          <endTime>2009-10-25T21:15:15.000Z</endTime>
          <listingType>Auction</listingType>
          <gift>false</gift>
        </listingInfo>
        <itemRank>3</itemRank>
        <itemRankWithinGroup>3</itemRankWithinGroup>
        <quantityAvailable>1</quantityAvailable>
        <quantitySold>0</quantitySold>
        <bestMatchData>
          <freeShipping>false</freeShipping>
          <impressionCountRange>
            <min>1</min>
            <max>50</max>
          </impressionCountRange>
          <salesCount>0</salesCount>
          <viewItemCount>7</viewItemCount>
          <watchCount>1</watchCount>
          <salesPerImpression>0.0</salesPerImpression>
          <salesPerViewItem>0.0</salesPerViewItem>
          <viewItemPerImpression>0.18425</viewItemPerImpression>
        </bestMatchData>
      </item>
    </searchItemGroup>
    <totalEntries>3</totalEntries>
  </searchResult>
  <paginationOutput>
    <totalPages>1</totalPages>
    <totalEntries>3</totalEntries>
    <pageNumber>1</pageNumber>
    <entriesPerPage>50</entriesPerPage>
  </paginationOutput>
</findBestMatchItemDetailsBySellerResponse>

findBestMatchItemDetailsBySeller Change History

Version	Description
1.5.0 04/14/2010	ItemFilterType values (added): New filters (BestOfferOnly, ExcludeCategory, ModTimeFrom) to control search results.
1.2.0 11/11/2009	searchResult.searchItemGroup.item.galleryPlusPictureURL (added): Image URL for items listed with Gallery Plus upgrade. itemFilter.name.SellerBusinessType (doc change): Corrected the allowed filter values to include Business and Private only. itemFilter.name.Condition (doc change): Corrected the allowed filter values to include Unspecified.
1.0.1 09/30/2009	(added) New call.

User-Contributed Notes

categoryId	string	Required	The category from which you want to retrieve Best Match information. Also returns information on all children of the specified category. If you repeat this field in the request, the BestMatchItemDetails Service only recognizes the last categoryId field. If the specified category ID doesn't match an existing site category, the service returns an invalid-category error message.
ignoreFeatured	boolean	Optional	Specifies whether or not to include Featured items in the response. The value is false by default (Featured items are included in the response). Default: false.
itemFilter	ItemFilter	Optional, repeatable: [0..*]	Reduces the number of items returned in the response according to the filters you specify.
itemFilter.name	ItemFilterType	Optional	Specify the name of the item filter you want to use. The itemFilter name must have a corresponding value. You can apply multiple itemFilter Name/Value pairs in a single request. See the ItemFilterType type documentation for more information about the allowed values, usage rules, and dependencies. Refer to the following samples to see itemFilters in action: Using itemFilters to define a price range Using itemFilters to search for used Buy It Now items Applicable values: See name.
itemFilter.paramName	token	Optional	In addition to itemFilter Name/Value pairs, some itemFilters use an additional parameter Name/Value pair. Specifically, filters that use currency values (MaxPrice and MinPrice) make use of addition parameters. When you use these itemFilters, set paramName to Currency and provide the currency ID in paramValue. For example, if you use the MaxPrice itemFilter, you will need to specify a parameter Name of Currency with a parameter Value that specifies the type of currency desired. Note that for MaxPrice and MinPrice itemFilters, the default value for paramName is Currency.
itemFilter.paramValue	string	Optional	The currency value associated with the respective itemFilter parameter Name. Usually paramName is set to Currency and paramValue is set to the currency type in which the monetary transaction occurs. For a list of possible currency enumeration values, see currencyId Values. Note that for MaxPrice and MinPrice itemFilters, the default value for paramValue is USD.
itemFilter.value	string	Optional, repeatable: [1..*]	The value associated with the respective itemFilter Name.
paginationInput	PaginationInput	Optional	Controls the pagination of the result set. Elements of this type specify the maximum number of item listings to return per call and the page of data to return. Controls the number of listings returned in the response, but does not specify the details to return for each listing. Note: No more than 10,000 items can be retrieved for a given search, regardless of how many matches are found. This limit is enforced by the maximum number of pages allowed (100) and the maximum number of entries per page (100).
paginationInput.entriesPerPage	int	Optional	Specifies the maximum number of entries to return in a single call. If the number of entries found on the specified pageNumber is less than the value specified here, the number of items returned will be less than the value of entriesPerPage. This indicates the end of the result set. If entriesPerPage is set to a number greater than 100, the default value of 100 is used. Default: 100.
paginationInput.pageNumber	int	Optional	Specifies which subset of data (or "page") to return in the call response. The number of data pages is determined by the total number of items matching the request search criteria (returned in paginationOutput.totalEntries) divided by the number of entries to display in each response (entriesPerPage). You can return up to the first 100 pages of the result set by issuing multiple requests and specifying, in sequence, the pages to return. Default: 1.
sellerUserName	string	Required	User name of the seller whose item listings you want to review. If sellerUserName equals the name of the authorized caller of the function, the Service also returns Best Match information about the items returned.

eBay Best Match Item Details API Call Reference Version 1.7.0