Skip to main content

The following table contains the details of the field filters supported in the Buy APIs. You use these filters to control the items returned in the response. You can use more that one filter in a method. Not all of these filters are supported by all Buy API methods. The API/Method column shows you which Buy API methods support that filter.

Note: Query parameter values need to be URL encoded. For details, see URL encoding query parameter values. For readability, code examples in this document have not been URL encoded.

Filter name API/Method Syntax Description
bidCount Browse:
  • search
  • searchByImage
filter=bidCount:[1..5]

Only items with a number of bids within the specified range are returned.

The first value is the lower number of bids and the second value is the higher number of bids. The lower and higher values are separated by two dots ('..'). In the syntax example provided, only items with 1 to 5 bids would be returned.

It is possible to specify only a lower or a higher value.
  • If you specify only a lower value, the two dots ('..') are not needed and every item with at least that number of bids is returned.

      filter=bidCount:[1]
  • If you specify only a higher value, the two dots ('..') are required and every item with a number of bids up to that maximum is returned.

      filter=bidCount:[..5]

Note: This filter applies only to auction items

buyingOptions Browse
  • search
  • searchByImage
Marketplace Insights:
  • search
filter=buyingOptions:{FIXED_PRICE|BEST_OFFER}

Only items offering the specified buying formats are returned. Multiple values can be used for this filter and are separated by the pipe symbol - '|'.

Valid Values:

  • FIXED_PRICE - Items offered for a fixed-price (Buy It Now). These items can also be offered as an auction. Once a bid is placed, FIXED_PRICE is no longer available and the item is now only available as an auction. When this happens, that item will not be return using this filter.
  • AUCTION - Items offered only as an auction whether they have bids or not.
  • BEST_OFFER - Items where the buyer can send the seller a price they're willing to pay for the item. The seller can accept, reject, or send a counter offer. For details about Best Offer, see Best Offer.

    Note: This filter is not supported in the Marketplace Insights API.

  • CLASSIFIED_AD - Items that have been listed on eBay but state that the final sales transaction is to be completed outside of the eBay environment.
charityOnly Browse:
  • search
  • searchByImage
filter=charityOnly:true Only items associated with a charity are returned.
conditionIds Browse:
  • search
  • searchByImage
Marketplace Insights:
  • search
filter=conditionIds:{1000|1500}

Only items with the specified condition ID are returned. Multiple values can be used for this filter and are separated by the pipe symbol - '|'.

The conditionIds filter returns items of a specific condition that correspond to a numerical code, such as New (1000), Good (5000), and Seller Refurbished (2500).

For more information on item conditions for some popular eBay categories, see the Item Condition IDs and Names.

conditions Browse:
  • search
  • searchByImage
Marketplace Insights:
  • search
filter=conditions:{NEW|USED}

Only items in the specified conditions are returned. Item condition values can vary by category. Multiple values can be used for this filter and are separated by the pipe symbol - '|'.

Unlike the conditionID filter, the conditions filter will not return items of a specific condition such as Good, Very Good, or Seller Refurbished. It will only return items that are categorized by the broader conditions of NEW and USED. To get results for specific conditions, please use the conditionID filters.

For more information on item conditions for some popular eBay categories, see the Item conditions by category help topic.

Valid Values (case sensitive):
  • NEW
  • USED
  • UNSPECIFIED
deliveryCountry Browse:
  • search
  • searchByImage
filter=deliveryCountry:US

Only items that can be shipped to the specified country are returned.

Restriction: This filter is ignored when used with the pickupCountry, pickupPostalCode, pickupRadius, and pickupRadiusUnit filters.

Valid Values (case sensitive): Two-character ISO 3166 Country Code.
deliveryOptions Browse:
  • search
  • searchByImage
filter=deliveryOptions:{SELLER_ARRANGED_LOCAL_PICKUP}

Only local pickup items are returned.

Requirement:This filter must be used with the pickupCountry, pickupPostalCode, pickupRadius, and pickupRadiusUnit filters.

Valid Values:
  • SELLER_ARRANGED_LOCAL_PICKUP
deliveryPostalCode Browse:
  • search
  • searchByImage
filter=deliveryPostalCode:95125

Only items that can be shipped to the specified postal/zip code are returned.

Restriction: This filter is ignored when used with the pickupCountry, pickupPostalCode, pickupRadius, and pickupRadiusUnit filters.

Requirement: This filter must be used with the deliveryCountry filter.

Example: filter=deliveryPostalCode:95125,deliveryCountry:US
excludeSellers Browse:
  • search
  • searchByImage
filter=excludeSellers:{rpsseller|bigSales}

Any items from the specified sellers are not returned in the response. Multiple values can be used for this filter and are separated by the pipe symbol - '|'.

Valid Values: The sellers' eBay user ID.
excludeCategoryIds Browse:
  • search
  • searchByImage
filter=excludeCategoryIds:{15032|31387} Any item in the specified categories will not be returned. Multiple values can be used for this filter and are separated by the pipe symbol - '|'.
guaranteedDeliveryInDays Browse:
  • search
  • searchByImage
Not applicable

This filter value has been deprecated. eBay Guaranteed Delivery is no longer a supported feature on any marketplace.

itemEndDate Browse:
  • search
  • searchByImage
filter=itemEndDate:[2018-11-14T07:47:48Z..2018-12-14T07:47:48Z]

Only items scheduled to end within the specified date-time range are returned. The first date-time value is the start of the range and the second date-time value is the end of the range. The start and end range value are separated by two dots ('..').

It is possible to only use a start range value or only use an end range value.
  • If only specifying a start range value, the two dots ('..') are not needed and every listing ending after that is returned.

    filter=itemEndDate:[2018-11-14T07:47:48Z]
  • If only specifying the end range value, the two dots ('..') are required before the end range value and every listing ending before that is returned.

    filter=itemEndDate:[..2018-12-14T07:47:48Z]
Valid Values: UTC Format (yyyy-MM-ddThh:mm:ss.sssZ) (ISO 8601 standard)
itemStartDate Browse:
  • search
  • searchByImage
filter=itemStartDate:[2018-11-14T07:47:48Z..2018-12-14T07:47:48Z]

Only items scheduled to start within the specified date-time range are returned. The first date-time value is the start of the range and the second date-time value is the end of the range. The start and end range value are separated by two dots ('..').

Note: This filter is based on the timestamp recorded by eBay the moment the listing became available. This value does not necessarily equal the value returned in itemCreationDate.


It is possible to only use a start range value or only use an end range value.
  • If only specifying a start range value, the two dots ('..') are not needed and every listing starting after that is returned.

    filter=itemEndDate:[2018-11-14T07:47:48Z]

  • If only specifying the end range value, the two dots ('..') are required before the end range value and every listing starting before that is returned.

    filter=itemEndDate:[..2018-12-14T07:47:48Z]

Valid Values: UTC Format (yyyy-MM-ddThh:mm:ss.sssZ) (ISO 8601 standard)
itemLocationCountry Browse:
  • search
  • searchByImage

Marketplace Insights:

  • search
filter=itemLocationCountry:US

Only items located in the specified country are returned.

Restrictions: Valid Values (case sensitive): Two-character ISO 3166 Country Code
itemLocationRegion Browse:
  • search
filter=itemLocationRegion:WORLDWIDE

Only items located in the specified region are returned.

Restrictions: 

Valid Values:

  • ASIA

  • BORDER_COUNTRIES

  • CONTINENTAL_EUROPE

  • EUROPEAN_UNION

  • NORTH_AMERICA

  • UK_AND_IRELAND

  • WORLDWIDE

lastSoldDate Marketplace Insights:
  • search
filter=lastSoldDate:[2018-08-30T00:00:00Z..2018-09-17T00:00:00Z]

Only items sold within the date range period are returned.

Valid Values: UTC Format (yyyy-MM-ddThh:mm:ss.sssZ) (ISO 8601 standard)
maxDeliveryCost Browse:
  • search
  • searchByImage
filter=maxDeliveryCost:0

Only items with free shipping are returned.

Valid Values: 0 (zero)
paymentMethods Browse:
  • search
  • searchByImage
filter=paymentMethods:{CREDIT_CARD}

Only items that offer payment by credit card are returned.

Valid Values: CREDIT_CARD
pickupCountry Browse:
  • search
  • searchByImage
filter=pickupCountry:US

This filter, along with the three other pickup filters, sets the local pickup radius. Only items that are available through local pickup and within the pickup radius set by the user are retrieved.

Requirement: The method must include all the pickup filters (pickupCountry, pickupPostalCode, pickupRadius, and pickupRadiusUnit) and the deliveryOptions filter.

Valid Values (case sensitive): Two-character ISO 3166 Country Code
pickupPostalCode Browse:
  • search
  • searchByImage
filter=pickupPostalCode:95125

This filter, along with the three other pickup filters, sets the local pickup radius. Only items that are available through local pickup and within the pickup radius set by the user are retrieved. The pickupPostalCode value is generally the postal code of the buyer's address.

Requirement: The method must include all the pickup filters (pickupCountry, pickupPostalCode, pickupRadius, and pickupRadiusUnit) and the deliveryOptions filter.

Valid Values: A postal or zip code.
pickupRadius Browse:
  • search
  • searchByImage
filter=pickupRadius:25

This filter, along with the three other pickup filters, sets the local pickup radius. Only items that are available through local pickup and within the pickup radius set by the user are retrieved.

The pickupRadius value defines the distance that the buyer iswilling to travel (in miles or km) from the postal code defined in the pickupPostalCode filter to pick up the item.

Requirement: The method must include all the pickup filters (pickupCountry, pickupPostalCode, pickupRadius, and pickupRadiusUnit) and the deliveryOptions filter.
pickupRadiusUnit Browse:
  • search
  • searchByImage
filter=pickupRadiusUnit:mi

This filter, along with the three other pickup filters, sets the local pickup radius. Only items that are available through local pickup and within the pickup radius set by the user are retrieved. The pickupRadiusUnit defines the distance measurement unit used for the pickup radius.

Requirement: The method must include all the pickup filters (pickupCountry, pickupPostalCode, pickupRadius, and pickupRadiusUnit) and the deliveryOptions filter.

Valid Values:
  • mi

  • km

price Browse:
  • search
  • searchByImage

Marketplace Insights:

  • search
filter=price:[10..50]

Only items with prices within the specified price range are returned. This filter supports double data type values. The first double value is the lower monetary value and the second double value is the higher monetary value.

In the example below, only items priced from $10.00 to $50.00 would be returned. The lower and higher monetary value are separated by two dots ('..').

It is possible to only use a lower or a higher monetary value.
  • If you only specify a lower monetary value, the two dots ('..') are not needed and every item priced at or above that price is returned.

    filter=price:[10]

  • If you only specify a higher monetary value, the two dots ('..') are required and every item priced below or at that price is returned.

    filter=price:[..50]

Requirement: This filter must be used with the priceCurrency filter.

Example: filter=price:[50..500],priceCurrency:USD
priceCurrency Browse:
  • search
  • searchByImage

Marketplace Insights:

  • search
filter=priceCurrency:USD

Specifies the currency tied to the price.

Valid Values (case sensitive): The three-digit Currency codes (ISO 4217 standard).

Restriction: This filter is only needed if the price (range) filter is used.

For example: filter=price:[50..500],priceCurrency:USD
priorityListing Browse:
  • search
filter=priorityListing:true

Only items that are a part of a Promoted Listings campaign are retrieved.

Note: For this filter to have an effect, the sort option must be set to Best Match (default).

qualifiedPrograms Browse:
  • search
  • searchByImage
filter=qualifiedPrograms:{EBAY_PLUS|AUTHENTICITY_GUARANTEE|AUTHENTICITY_VERIFICATION}

Only items that are eligible for eBay qualified programs, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION, are returned.

Note: In order for the search method to return items for this container, the filters deliveryCountry and deliveryPostalCode must be present.

eBay Plus is a premium account option for buyers, which provides benefits such as fast free domestic shipping and free returns on selected items. Top-Rated eBay sellers must opt in to eBay Plus to be able to offer the program on qualifying listings. Sellers must commit to next-day delivery of those items

Note: eBay Plus is available only to buyers in Germany, Austria, and Australia. Authenticity Guarantee is available only for items purchased on eBay.com.

The eBay Authenticity Guarantee program enables third-party authenticators to perform authentication verification inspections on items such as watches and sneakers.

The eBay Authenticity Verification program returns listings from verified sellers.

Valid Values (case sensitive):
  • EBAY_PLUS
  • AUTHENTICITY_GUARANTEE
  • AUTHENTICITY_VERIFICATION
returnsAccepted Browse:
  • search
  • searchByImage
filter=returnsAccepted:true

When set to "true", only items that can be returned to the seller are returned. If this is null, items are returned regardless of the seller's return policy.

Valid Value: true
searchInDescription Browse:
  • search
filter=searchInDescription:true

Only items with a title or description matching the specified keyword are returned.

Valid Value: true
sellerAccountTypes Browse:
  • search
  • searchByImage

filter=sellerAccountTypes:{INDIVIDUAL}

or

filter=sellerAccountTypes:{BUSINESS}

Only items from the specified seller account type are returned in the response. The seller account type indicates if the seller is a business or an individual.

This is determined when the seller registers with eBay. If they register for a business account, they have a business account. If they register for a private account, they have an individual account. This designation is required by the tax laws in some countries.

This filter is supported on the following sites:
  • EBAY_AT (Austria)
  • EBAY_BE (Belgium)
  • EBAY_CH (Switzerland)
  • EBAY_DE (Germany)
  • EBAY_ES (Spain)
  • EBAY_FR (France)
  • EBAY_GB (Great Britain)
  • EBAY_IE (Ireland)
  • EBAY_IT (Italy)
  • EBAY_PL (Poland)

Restriction: You can filter by either BUSINESS or INDIVIDUAL. But you cannot filter by both.

Valid Values (case sensitive):
  • BUSINESS
  • INDIVIDUAL
sellers Browse:
  • search
  • searchByImage
filter=sellers:{rpsSeller|bigSales}

Only items from the specified sellers are returned in the response. Multiple values can be used for this filter and are separated by the pipe symbol '|'.

Restriction: Running a search with more than 250 sellers will generate an error message. This filter limits the maximum number of sellers to 250.

Valid Values: The sellers' eBay user ID.

Valid itemLocationRegion Values

Supported values for the itemLocationRegion filter vary by marketplace. See the table below for valid values for each marketplace:

Marketplace Valid Values
EBAY_US NORTH_AMERICA, WORLDWIDE
EBAY_GB EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EBAY_DE EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EBAY_CA NORTH_AMERICA, WORLDWIDE
EBAY_AU WORLDWIDE
EBAY_FR EUROPEAN_UNION, CONTINENTAL_EUROPE, BORDER_COUNTRIES, WORLDWIDE
EBAY_IT EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EBAY_ES EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EBAY_BE EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EBAY_AT EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EBAY_CH EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EBAY_NL EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EABY_PL EUROPEAN_UNION, CONTINENTAL_EUROPE, WORLDWIDE
EBAY_IE EUROPEAN_UNION, CONTINENTAL_EUROPE, UK_AND_IRELAND, WORLDWIDE
EBAY_SG ASIA, WORLDWIDE
EBAY_HK ASIA, BORDER_COUNTRIES, WORLDWIDE

Got thoughts? Click the feedback button – your insights help us improve!