Buy API Field Filters

• search
• searchByImage

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.

• 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]

• search
• searchByImage

• search

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.

• search
• searchByImage

• search
• searchByImage

• search

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.

• search
• searchByImage

• search

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.

• NEW
• USED
• UNSPECIFIED

• search
• searchByImage

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.

• search
• searchByImage

Only local pickup items are returned.

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

• SELLER_ARRANGED_LOCAL_PICKUP

• search
• searchByImage

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.

• search
• searchByImage

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

• search
• searchByImage

• search
• searchByImage

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

• search
• searchByImage

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

• 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]

• search
• searchByImage

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

• 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]

• search
• searchByImage

Marketplace Insights:

• search

Only items located in the specified country are returned.

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

• This filter cannot be used with the itemLocationRegion filter. If both filters are used, an error will occur.

• Only one country code value can be used for this filter.

• search

Only items located in the specified region are returned.

Restrictions: 

• This filter cannot be used with the itemLocationCountry filter. If both filters are used, an error will occur.

• Supported values vary by marketplace. See Valid itemLocationRegion Values for valid values for each marketplace.

Valid Values:

• ASIA

• BORDER_COUNTRIES

• CONTINENTAL_EUROPE

• EUROPEAN_UNION

• NORTH_AMERICA

• UK_AND_IRELAND

• WORLDWIDE

• search

Only items sold within the date range period are returned.

• search
• searchByImage

Only items with free shipping are returned.

• search
• searchByImage

Only items that offer payment by credit card are returned.

• search
• searchByImage

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.

• search
• searchByImage

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.

• search
• searchByImage

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.

• search
• searchByImage

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.

• mi

• km

• search
• searchByImage

Marketplace Insights:

• search

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

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

• search
• searchByImage

Marketplace Insights:

• search

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.

• search

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

• search
• searchByImage

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

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

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.

• EBAY_PLUS
• AUTHENTICITY_GUARANTEE
• AUTHENTICITY_VERIFICATION

• search
• searchByImage

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.

• search

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

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

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

• BUSINESS
• INDIVIDUAL

• search
• searchByImage

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.