eBay Finding API1.13.0

Applicable values for findItemsByProductRequest.itemFilter.name

AuthorizedSellerOnly
If set to true, returns only items listed by authorized sellers.

Allowed values (boolean):
true, false

AvailableTo
Limits items to those available to the specified country only. Item filter LocatedIn cannot be used together with item filter AvailableTo.

Allowed values (string):
Expects the two-letter ISO 3166 country code to indicate the country where the item is located. For English names that correspond to each code (for example, KY="Cayman Islands"), see the ISO site:
http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm.

BestOfferOnly
If true, the search results are limited to only items that have Best Offer enabled. Default is false.

Allowed values (boolean):
true, false

CharityOnly
If true, the search results are limited to items for which all or part of the proceeds are given to a charity. Each item in the search results will include the ID of the given charity. Default is false.

Allowed values (boolean):
true, false

Condition
Limits items to those that have the matching item condition. The order of the results depends on the sortOrder you specify (not ordered by conditions).

Mostly useful to filter items where the seller used one of eBay's structured item condition formats (conditionId or item specifics) to specify the item condition. If the seller used item specifics, the condition is only returned in conditionDisplayName.

If you repeat condition values, the values are processed using OR logic. For example:
To precisely find only brand new and manufacturer-refurbished items, pass the filter with values of 1000 and 2000 in the same request.
To find all flavors of new items plus refurbished items (but not used items), pass the filter with values of New, 2000, and 2500.
To find a much broader set of new items, plus items with no condition specified, pass the filter with values of New and Unspecified.
(The order of the values does not affect the results. That is, passing New, 2000, and then 2500 gives the same results as passing 2000, New, and then 2500.)

Allowed text values (string):
These text values (except Unspecified) limit results to items with the condition defined in conditionId or item specifics.

New
New (or the equivalent). Excludes items with used, refurbished, for parts, or unspecified conditions.
Used
Used, refurbished, or for parts. Excludes items with new or unspecified conditions.
Unspecified
The seller did not specify an item condition using one of eBay's structured formats. That is, either the item has no condition, or the seller only specified the condition in the title or narrative description. (You can try including words like "new" in your search keywords to reduce unspecified results. In this case, if you're using findItemsAdvanced, you can also try setting descriptionSearch to true to find items with the condition value in the description.) Excludes items that the seller listed as new, used, refurbished, for parts, or the equivalent.

Allowed ID values (string):
These IDs limit results to items with the condition defined in conditionId.

For details about the meaning of each condition, see Item Condition IDs and Names. More importantly, always see the seller's listing for full details and description of any imperfections before purchasing an item.

1000
New
1500
New other (see details)
1750
New with defects
2000
Manufacturer refurbished
2500
Seller refurbished
3000
Used
4000
Very Good
5000
Good
6000
Acceptable
7000
For parts or not working
Example:
 ...
&itemFilter(0).name=Condition
&itemFilter(0).value(0)=New
&itemFilter(0).value(1)=2000
&itemFilter(0).value(2)=2500
...
Currency
Limits results to items listed with the specified currency only.

Allowed values (string):
For a list of allowed currency values, see currencyId Values.

EndTimeFrom
Limits the results to items ending on or after the specified time. Specify a time in the future.

Allowed values (dateTime):
Specify the time in GMT.

EndTimeTo
Limits the results to items ending on or before the specified time. Specify a time in the future.

Allowed values (dateTime):
Specify the time in GMT.

ExcludeAutoPay
If true, excludes all items requiring immediate payment. Default is false.

Allowed values (boolean):
true, false

ExcludeCategory
Specify one or more category IDs. Search results will not include items from the specified categories or their child categories.

Allowed values (string):
Valid category IDs.

Note: Multiple values are allowed. Up to 25 categories can be specified.

Example:
 ...
&itemFilter(0).name=ExcludeCategory
&itemFilter(0).value(0)=168093
&itemFilter(0).value(1)=56170
&itemFilter(0).value(2)=73834
...
ExcludeSeller
Specify one or more seller names. Search results will not include items from the specified sellers. The ExcludeSeller item filter cannot be used together with either the Seller or TopRatedSellerOnly item filters.

Allowed values (string):
Valid seller names.

Note: Multiple values are allowed. Up to 100 sellers can be specified.

Example:
 ...
&itemFilter(0).name=ExcludeSeller
&itemFilter(0).value(0)=seller01
&itemFilter(0).value(1)=seller02
&itemFilter(0).value(2)=seller03
...
ExpeditedShippingType
Specifies the type of expedited shipping. You can specify either Expedited or OneDayShipping. Only items that can be shipped by the specified type are returned.

ExpeditedShippingType is used together with the MaxHandlingTime and ReturnsAcceptedOnly filters to filter items for certain kinds of gifting events such as birthdays or holidays where the items must be delivered by a certain date. If you wish to mimic the behavior of the eBay holiday filters, you would use ExpeditedShippingType set to either Expedited or OneDayShipping, MaxHandlingTime to 1, ReturnsAcceptedOnly set to true, and for the Germany site, set PaymentMethod to PayPal. (The holiday filters may not always be available in the eBay UI, depending on the season; however, the equivalent filter behavior continues to be available in the API.)

Allowed values (string):
Expedited, OneDayShipping

FeaturedOnly
If true, the search results are limited to featured item listings only. Default is false.

Allowed values (boolean):
true, false

FeedbackScoreMax
Specifies the maximum feedback score of a seller whose items can be included in the response. If FeedbackScoreMin is also specified, the FeedbackScoreMax value must be greater than or equal to the FeedbackScoreMin value.

Allowed values (int):
Integer greater than or equal to 0.

FeedbackScoreMin
Specifies the minimum feedback score of a seller whose items can be included in the response. If FeedbackScoreMax is also specified, the FeedbackScoreMax value must be greater than or equal to the FeedbackScoreMin value.

Allowed values (int):
Integer greater than or equal to 0.

FreeShippingOnly
If true, the search results are limited to only items with free shipping to the site specified in the request (see Global ID Values). Default is false.

Allowed values (boolean):
true, false

GetItFastOnly
If true, the search results are limited to only Get It Fast listings. Default is false.

Allowed values (boolean):
true, false

HideDuplicateItems
If true, and there are duplicate items for an item in the search results, the subsequent duplicates will not appear in the results. Default is false.
Item listings are considered duplicates when all of the following conditions are met:
1. Items are listed by the same seller
2. Items have exactly the same item title
3. Items have similar listing formats:
    - Auctions (Auction Items and Auction BIN items)
    - Fixed Price (Fixed Price, Multi-quantity Fixed Price, and Fixed Price with Best Offer Format items)
    - Classified Ads

For Auctions, items must also have the same price and number of bids to be considered duplicates.

Allowed values (boolean):
true, false

ListedIn
The site on which the items were originally listed. This can be useful for buyers who wish to see only items on their domestic site either for delivery cost reasons or time reasons, such as for gifting occasions like birthdays or holidays.

Allowed values (Global ID Values):

GlobalID Value

ListingType
Filters items based listing type information. Default behavior is to return all matching items.

Allowed values (string):
Auction
Retrieves matching auction listings (i.e., listings eligible for competitive bidding at auction) only. Excludes auction items with Buy It Now.
AuctionWithBIN
Retrieves all matching auction listings with Buy It Now available. Excludes auction listings without Buy It Now. An auction listed with Buy It Now will not be returned if a valid bid has been placed on the auction.
Classified
Retrieves Classified Ad format (i.e., Classified and AdFormat listing type) listings only.
FixedPrice
Retrieves matching fixed price items only.
All
Retrieves matching items for any listing type.

Note: Multiple listing type values can be specified for this filter.

Example:
 ...
&itemFilter(0).name=ListingType
&itemFilter(0).value(0)=AuctionWithBIN
&itemFilter(0).value(1)=FixedPrice
...

LocalPickupOnly
If true, the search results are limited to only items which have local pickup available. Default is false.

Allowed values (boolean):
true, false

LocalSearchOnly
If true, the search results are limited to only matching items with the Local Inventory Listing Options (LILO). Must be used together with the MaxDistance item filter, and the request must also specify buyerPostalCode. Currently, this is only available for the Motors site (global ID EBAY- MOTOR).

Allowed values (boolean):
true, false

LocatedIn
Limits the result set to just those items located in the specified country. Item filter AvailableTo cannot be used together with item filter LocatedIn.

Allowed values (string):
Expects the two-letter ISO 3166 country code to indicate the country where the item is located. For English names that correspond to each code (for example, KY="Cayman Islands"), see the ISO site:
http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm.

Note: Multiple values are allowed. Up to 25 countries can be specified.

LotsOnly
If true, the search results are limited to only matching listings for which the lot size is 2 or more. Default is false.

Allowed values (boolean):
true, false

MaxBids
Limits the results to items with bid counts less than or equal to the specified value. If MinBids is also specified, the MaxBids value must be greater than or equal to the MinBids value.

Allowed values (int):
Integer greater than or equal to 0.

MaxDistance
Specifies the maximum distance from the specified postal code (buyerPostalCode) to search for items. The request must also specify buyerPostalCode.

The minimum distance supported is 5 miles or 10 kilometers, depending upon whether the distance unit supported for the site to which the request is submitted is miles (mi) or kilometers (km). For example, the smallest MaxDistance for searches submitted to the US eBay site (global ID EBAY-US) is 5 (miles). The smallest MaxDistance for searches submitted to the Germany eBay site (global ID EBAY-DE) is 10 (kilometers).

Values are rounded up to the nearest 5 (mi) or 10 (km) increment. For example, a value of 21 will be rounded up to 25 (mi) on the eBay US site and to 30 (km) on the eBay Germany site.

Allowed values (int):
Integer greater than or equal to 5.

MaxHandlingTime
Specifies the maximum number of handling days the seller requires to ship the item. Only items with a handling time less than or equal to this number will be returned. (The handling time is the amount of time, in days, required by the seller to get the item ready to ship and handed off to the actual carrier who does the delivery. It does not include the time required by the carrier to deliver the item.

ExpeditedShippingType is used together with the MaxHandlingTime and ReturnsAcceptedOnly filters to filter items for certain kinds of gifting events such as birthdays or holidays where the items must be delivered by a certain date. If you wish to mimic the behavior of the eBay holiday filters, you would use ExpeditedShippingType set to either Expedited or OneDayShipping, MaxHandlingTime to 1, ReturnsAcceptedOnly set to true, and for the Germany site, set PaymentMethod to PayPal. (The holiday filters may not always be available in the eBay UI, depending on the season; however, the equivalent filter behavior continues to be available in the API.)

Allowed values (int):
Integer greater than or equal to 1.

MaxPrice
Specifies the maximum current price an item can have to be included in the response. Optionally, you can also specify a currency ID, using the paramName and paramValue fields (for example, ¶mName=Currency¶mValue=EUR). If using with MinPrice to specify a price range, the MaxPrice value must be greater than or equal to MinPrice.

Allowed values (decimal):
Decimal values greater than or equal to 0.0.

MaxQuantity
Limits the results to listings with a quantity less than or equal to the specified value. If MinQuantity is also specified, the MaxQuantity value must be greater than or equal to the MinQuantity value.

Allowed values (int):
Integer greater than or equal to 1.

MinBids
Limits the results to items with bid counts greater than or equal to the specified value. If MaxBids is also specified, the MaxBids value must be greater than or equal to the MinBids value.

Allowed values (int):
Integer greater than or equal to 0.

MinPrice
Specifies the minimum current price an item can have to be included in the response. Optionally, you can also specify a currency ID, using the paramName and paramValue fields (for example, ¶mName=Currency¶mValue=EUR). If using with MaxPrice to specify a price range, the MaxPrice value must be greater than or equal to MinPrice.

Allowed values (decimal):
Decimal values greater than or equal to 0.0.

MinQuantity
Limits the results to listings with a quantity greater than or equal to the specified value. If MaxQuantity is also specified, the MaxQuantity value must be greater than or equal to the MinQuantity value.

Allowed values (int):
Integer greater than or equal to 1.

ModTimeFrom
Limits the results to active items whose status has changed since the specified time. Specify a time in the past. Time must be in GMT.

Allowed values (dateTime):
Specify the time in GMT.

OutletSellerOnly
If set to true, returns only items listed by sellers at eBay's outlet stores, such as the Fashion Outlet.

Allowed values (boolean):
true, false

PaymentMethod
Limits results to items that accept the specified payment method.

Allowed values (string):
PayPal
PayPal payment method.
PaisaPay
PaisaPay payment method. The PaisaPay payment method is only for the India site (global ID EBAY-IN).
PaisaPayEMI
PaisaPayEscrow EMI (Equal Monthly Installment) payment method. The PaisaPayEscrowEMI payment method is only for the India site (global ID EBAY-IN).

ReturnsAcceptedOnly
If set to true, returns only items where the seller accepts returns.

ExpeditedShippingType is used together with the MaxHandlingTime and ReturnsAcceptedOnly filters to filter items for certain kinds of gifting events such as birthdays or holidays where the items must be delivered by a certain date. If you wish to mimic the behavior of the eBay holiday filters, you would use ExpeditedShippingType set to either Expedited or OneDayShipping, MaxHandlingTime to 1, ReturnsAcceptedOnly set to true, and for the Germany site, set PaymentMethod to PayPal. (The holiday filters may not always be available in the eBay UI, depending on the season; however, the equivalent filter behavior continues to be available in the API.)

Allowed values (boolean):
true, false

Seller
Specify one or more seller names. Search results will include items from the specified sellers only. The Seller item filter cannot be used together with either the ExcludeSeller or TopRatedSellerOnly item filters.

Allowed values (string):
Valid seller names.

Note: Multiple values are allowed. Up to 100 sellers can be specified.

Example:
 ...
&itemFilter(0).name=Seller
&itemFilter(0).value(0)=seller01
&itemFilter(0).value(1)=seller02
&itemFilter(0).value(2)=seller03
...
SellerBusinessType
Restricts the items to those that are from sellers whose business type is the specified value. Only one value can be specified.

Not supported on all sites. Applies only to the following sites, which support seller business features:
  • Austria (EBAY-AT)
  • Belgium - Dutch (EBAY-NLBE)
  • Belgium - French (EBAY-FRBE)
  • France (EBAY-FR)
  • Germany (EBAY-DE)
  • Ireland (EBAY-IE)
  • Italy (EBAY-IT)
  • Poland (EBAY-PL)
  • Spain (EBAY-ES)
  • Switzerland (EBAY-CH)
  • UK (EBAY-GB)

Allowed values (string):
Business
The seller is registered as a business on eBay.
Private
The seller is registered as an individual on eBay.

StartTimeFrom
Limits the results to items started on or after the specified time. Specify a time in the future.

Allowed values (dateTime):
Specify the time in GMT.

StartTimeTo
Limits the results to items started on or before the specified time. Specify a time in the future.

Allowed values (dateTime):
Specify the time in GMT.

TopRatedSellerOnly
If true, the search results are limited to only matching items where the seller qualifies as a top-rated seller on the specified site. Site is specified with the global ID header or URL parameter. The default global ID value is EBAY- US (the eBay US site). Default for this filter is false.

The TopRatedSellerOnly item filter cannot be used together with either the Seller or ExcludeSeller item filters.

Allowed values (boolean):
true, false

ValueBoxInventory
Coming Soon: This filter can be used in conjunction with the sortOrder PricePlusShippingLowest to return competitively priced items from eBay top-rated sellers that have a BuyItNow price, with the lowest priced item at the top of the list. This filter returns items from categories that are catalog-enabled; items from non catalog-enabled categories are not returned. Sellers can use this item filter to determine competitive pricing; buying applications can use it to obtain competitive items from top rated sellers that are likely to sell quickly.

If set to 1, the item filter constraints are applied and the items are returned accordingly. If set to 0 (zero) the item filter is not applied. Defaults to 0.

Allowed values (boolean):
1, 0

WorldOfGoodOnly
If true, the search results are limited to only items listed in the World of Good marketplace. Defaults to false.

Allowed values (boolean):
true, false

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