Buy API Field Filters

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

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

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

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

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
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-characterISO 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 is willing 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
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 Values: 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 '|'.

Valid Values: The sellers' eBay user ID.