GET/item_summary/search
This method searches for eBay items by various query parameters and retrieves summaries of the items. You can search by keyword, category, eBay product ID (ePID), or GTIN, charity ID, or a combination of these.
Note: Only listings where FIXED_PRICE (Buy It Now) is a buying option are returned by default. To retrieve listings that do not have FIXED_PRICE as a buying option, the buyingOptions filter can be used to retrieve those listings.
Note that an auction listing enabled with the 'Buy it Now' feature will initially show AUCTION and FIXED_PRICE as buying options, but if/when that auction listing receives a qualifying bid, only AUCTION would remain as a buying option. If this happens, the buyingOptions filter would need to be used to retrieve that auction listing.
This method also supports the following:
- Filtering by the value of one or multiple fields, such as listing format, item condition, price range, location, and more. For the fields supported by this method, see the filter parameter.
- Retrieving the refinements (metadata) of an item , such as item aspects (color, brand), condition, category, etc. using the fieldgroups parameter.
- Filtering by item aspects and other refinements using the aspect_filter parameter.
- Filtering for items that are compatible with a specific product, using the compatibility_filter parameter.
- Creating aspects histograms, which enables shoppers to drill down in each refinement narrowing the search results.
For details and examples of these capabilities, see Browse API in the Buying Integration Guide.
Pagination and sort controls
There are pagination controls (limit and offset fields) and sort query parameters that control/sort the data that is returned. By default, the results are sorted by "Best Match". For more information about Best Match, see the eBay help page Best Match.
Request headers
This method uses the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Network and to improve the accuracy of shipping and delivery time estimations. For details see, Request headers in the Buying Integration Guide.Restrictions
This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to receive a commission for your sales, you must use the URL returned in theitemAffiliateWebUrl
field to forward your buyer to the ebay.com site.Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com
root URI with api.sandbox.ebay.com
URI parameters
Parameter | Type | Description |
---|---|---|
q | string | A string consisting of one or more keywords that are used to search for items on eBay. The keywords are handled as follows:
* wildcard character is not allowed in this field.Required: The method must have category_ids, epid, gtin, or q (or any combination of these). Occurrence: Optional |
gtin | string | This field lets you search by the Global Trade Item Number of the item as defined by https://www.gtin.info. You can search only by UPC (Universal Product Code). If you have other formats of GTIN, you need to search by keyword. For example: /buy/browse/v1/item_summary/search?gtin=099482432621 Maximum: 1 Required: The method must have category_ids, epid, gtin, or q (or any combination of these) Occurrence: Optional |
charity_ids | array of string | The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities. For example: /buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469 The charity ID is the charity's registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called "Charity Number".
category_Ids and q fields with a charity_Ids to filter the result set. This gives you additional control over the result set. Restriction: This is supported only on the US and GB marketplaces. Maximum: 20 IDs Required: One ID Occurrence: Optional |
fieldgroups | array of string | This field is a comma separated list of values that lets you control what is returned in the response. The default is MATCHING_ITEMS, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information. Valid Values:
Default: MATCHING_ITEMS Occurrence: Optional |
compatibility_filter | CompatibilityFilter | This field specifies the attributes used to define a specific product. The service searches for items matching the keyword or matching the keyword and a product attribute value in the title of the item. Note: The only products supported are cars, trucks, and motorcycles. For example, if the keyword is brakes and compatibility-filter=Year:2018;Make:BMW , the items returned are items with brakes, 2018, or BMW in the title.The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the CompatibilityMatchEnum value that indicates how well the item matches the attributes. Tip: See the Samples section for a detailed example. Best Practice: Submit all of the product attributes for the specific product. To find the attributes and values for a specific marketplace, you can use the getCompatibilityProperties method in the Taxonomy API. For more details, see Check compatibility in the Buy Integration Guide. Note: Testing in Sandbox is only supported using mock data. See Testing search in the Sandbox for details. Required:
Occurrence: Optional |
auto_correct | array of string | A query parameter that enables auto correction. Valid Values: KEYWORD Occurrence: Optional |
category_ids | array of string | The category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs. For example: /buy/browse/v1/item_summary/search?category_ids=29792 Note: Currently, you can pass in only one category ID per request. You can also use any combination of the category_Ids, epid, and q fields. This gives you additional control over the result set. For example, let's say you are looking of a toy phone. If you search for "phone", the result set will be mobile phones because this is the "Best Match" for this search. But if you also include the toy category ID, the results will be what you wanted. For example: /buy/browse/v1/item_summary/search?q=phone&category_ids=220 The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site:
Required: The method must have category_ids, epid, gtin, or q (or any combination of these) Occurrence: Optional |
filter | array of FilterField | An array of field filters that can be used to limit/customize the result set. For example: /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50] You can also combine filters. /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal} Note: Refer to Buy API Field Filters for details and examples of all supported filters. Occurrence: Optional |
sort | array of SortField | The order and field name that is used to sort the items. You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen ( - ) before the name of the sorting option. If no sort parameter is submitted, the result set is sorted by "Best Match".Here are some examples showing how to use the sort query parameter:
Occurrence: Optional |
limit | string | The number of items from the result set returned in a single page. Note: If a value is set in the limit field, the value of offset must be either zero or a multiple of the limit value. An error is returned for invalid values of offset. Note: This method can return a maximum of 10,000 items in one results set. Min: 1 Max: 200 Default: 50 Occurrence: Optional |
offset | string | Specifies the number of items to skip in the result set. This is used with the limit field to control the pagination of the output. For example, if offset is 0 and limit is 10, the method will retrieve items 1-10 from the list of items returned; if offset is 10 and limit is 10, the method will retrieve items 11-20 from the list of items returned. Note: The value of offset must be either zero or a multiple of the value set in the limit field. An error is returned for invalid values of offset. Note: This method can return a maximum of 10,000 items in one results set. Min: 0 Max: 9,999 Default: 0 Occurrence: Optional |
aspect_filter | AspectFilter | This field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red. For example, the method below uses the category ID for Women's Clothing. This will return only items for a woman's red shirt. /buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red} To get a list of the aspect pairs and the category, which is returned in the dominantCategoryId field, set fieldgroups to ASPECT_REFINEMENTS . /buy/browse/v1/item_summary/search?q=shirt&fieldgroups=ASPECT_REFINEMENTS Note: The pipe symbol is used as a delimiter between aspect filter values. If a value contains a pipe symbol (for example, the brand name 'Bed|Stü'), you must enter a backslash before the pipe character to prevent it from being evaluated as a delimiter. The following example shows the correct format for entering two brand names as aspect filter values, one of which contains a pipe symbol: /buy/browse/v1/item_summary/search?limit=50&category_ids=3034&filter=buyingOptions:{AUCTION|FIXED_PRICE}&aspect_filter=categoryId:3034,Brand:{Bed\|Stü|Nike} Required: The category ID is required twice; once as a URI parameter and as part of the aspect_filter. Occurrence: Optional |
epid | string | The ePID is the eBay product identifier of a product from the eBay product catalog. This field limits the results to only items in the specified ePID. The Marketing API getMerchandisedProducts method and the Browse API getItem, getItemByLegacyId, and getItemsByItemGroup calls return the ePID of the product. You can also use the product_summary/search method in the Catalog API to search for the ePID of the product. For example: /buy/browse/v1/item_summary/search?epid=15032 Maximum: 1 Required: The method must have category_ids, epid, gtin, or q (or any combination of these) Occurrence: Optional |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization
HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
Header | Type | Description |
---|---|---|
X-EBAY-C-ENDUSERCTX | string | This header is required to support revenue sharing for eBay Partner Network and to improve the accuracy of shipping and delivery time estimations. For additional information, refer to Use request headers. Occurrence: Optional |
X-EBAY-C-MARKETPLACE-ID | string | This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.See HTTP request headers for the marketplace ID values. Occurrence: Required |
OAuth scope
This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope
See OAuth access tokens for more information.
Request payload
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
Output container/field | Type | Description |
---|---|---|
autoCorrections | AutoCorrections | The auto-corrected inputs. Occurrence: Conditional |
autoCorrections.q | string | The automatically spell-corrected keyword from the request. Occurrence: Conditional |
href | string | The URI of the current page of results. Occurrence: Always |
itemSummaries | array of ItemSummary | An array of the items on this page. The items are sorted according to the sorting method specified in the request. Occurrence: Always |
itemSummaries.additionalImages | array of Image | An array of containers with the URLs for the images that are in addition to the primary image. The primary image is returned in the image.imageUrl field. Occurrence: Conditional |
itemSummaries.additionalImages.height | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.additionalImages.imageUrl | string | The URL of the image. Occurrence: Always |
itemSummaries.additionalImages.width | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.adultOnly | boolean | This indicates if the item is for adults only. For more information about adult-only items on eBay, see Adult items policy for sellers and Adult-Only items on eBay for buyers. Occurrence: Always |
itemSummaries.availableCoupons | boolean | This boolean attribute indicates if coupons are available for the item. Occurrence: Always |
itemSummaries.bidCount | integer | This integer value indicates the total number of bids that have been placed for an auction item. This field is only returned for auction items. Occurrence: Conditional |
itemSummaries.buyingOptions | array of string | A comma separated list of all the purchase options available for the item.
Occurrence: Always |
itemSummaries.categories | array of Category | This array returns the name and ID of each category associated with the item, including top level, branch, and leaf categories. Occurrence: Conditional |
itemSummaries.categories.categoryId | string | The unique identifier of the category. Occurrence: Always |
itemSummaries.categories.categoryName | string | The name of the category. Occurrence: Conditional |
itemSummaries.compatibilityMatch | CompatibilityMatchEnum | This indicates how well the item matches the compatibility_filter product attributes. Occurrence: Conditional |
itemSummaries.compatibilityProperties | array of CompatibilityProperty | This container returns only the product attributes that are compatible with the item. These attributes were specified in the compatibility_filter in the request. This means that if you passed in 5 attributes and only 4 are compatible, only those 4 are returned. If none of the attributes are compatible, this container is not returned. Occurrence: Conditional |
itemSummaries.compatibilityProperties.localizedName | string | The name of the product attribute that as been translated to the language of the site. Occurrence: Conditional |
itemSummaries.compatibilityProperties.name | string | The name of the product attribute, such as Make, Model, Year, etc. Occurrence: Conditional |
itemSummaries.compatibilityProperties.value | string | The value for the name attribute, such as BMW, R1200GS, 2011, etc. Occurrence: Conditional |
itemSummaries.condition | string | The text describing the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names. Occurrence: Conditional |
itemSummaries.conditionId | string | The identifier of the condition of the item. For example, 1000 is the identifier for NEW. For a list of condition names and IDs, see Item Condition IDs and Names. Occurrence: Conditional |
itemSummaries.currentBidPrice | ConvertedAmount | This container returns the current highest bid for an auction item. The value field shows the dollar value of the current highest bid, and the currency field (3-digit ISO code) denotes the currency associated with that bid value. This field is only returned for auction items. Occurrence: Conditional |
itemSummaries.currentBidPrice.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. Occurrence: Conditional |
itemSummaries.currentBidPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. Occurrence: Conditional |
itemSummaries.currentBidPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field. Occurrence: Conditional |
itemSummaries.currentBidPrice.value | string | The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. Occurrence: Conditional |
itemSummaries.distanceFromPickupLocation | TargetLocation | This container returns the distance away that the item is from the pickupPostalCode value that was supplied in the method request. This container is only returned if the 'local pickup' filter fields are used in the request. Occurrence: Conditional |
itemSummaries.distanceFromPickupLocation.unitOfMeasure | string | This value shows the unit of measurement used to measure the distance between the location of the item and the buyer's location. This value is typically Occurrence: Conditional |
itemSummaries.distanceFromPickupLocation.value | string | This value indicates the distance (measured in the measurement unit in the unitOfMeasure field) between the item location and the buyer's location. Occurrence: Conditional |
itemSummaries.energyEfficiencyClass | string | This indicates the European energy efficiency rating (EEK) of the item. Energy efficiency ratings apply to products listed by commercial vendors in electronics categories only. Occurrence: Conditional |
itemSummaries.epid | string | An ePID is the eBay product identifier of a product from the eBay product catalog. This indicates the product in which the item belongs. Occurrence: Conditional |
itemSummaries.image | Image | The URL to the primary image of the item. Occurrence: Always |
itemSummaries.image.height | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.image.imageUrl | string | The URL of the image. Occurrence: Always |
itemSummaries.image.width | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.itemAffiliateWebUrl | string | The URL to the View Item page of the item which includes the affiliate tracking ID.
Occurrence: Conditional |
itemSummaries.itemCreationDate | string | The date and time when the item listing was created. This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer. Occurrence: Conditional |
itemSummaries.itemEndDate | string | The date and time up to which the item can be purchased. This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer. Occurrence: Conditional |
itemSummaries.itemGroupHref | string | The HATEOAS reference of the parent page of the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. Occurrence: Conditional |
itemSummaries.itemGroupType | string | The indicates the item group type. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. Occurrence: Conditional |
itemSummaries.itemHref | string | The URI for the Browse API getItem method, which can be used to retrieve more details about items in the search results. Occurrence: Always |
itemSummaries.itemId | string | The unique RESTful identifier of the item. Occurrence: Always |
itemSummaries.itemLocation | ItemLocationImpl | This container returns the location of the item. This container consists of fields you typically see for an address, including postal code, county, state/province, street address, city, and country (2-digit ISO code). Occurrence: Conditional |
itemSummaries.itemLocation.addressLine1 | string | The first line of the street address. Occurrence: Conditional |
itemSummaries.itemLocation.addressLine2 | string | The second line of the street address. This field may contain such values as an apartment or suite number. Occurrence: Conditional |
itemSummaries.itemLocation.city | string | The city in which the item is located. Occurrence: Conditional |
itemSummaries.itemLocation.country | CountryCodeEnum | The two-letter ISO 3166 standard code that indicates the country in which the item is located. Occurrence: Always |
itemSummaries.itemLocation.county | string | The county in which the item is located. Occurrence: Conditional |
itemSummaries.itemLocation.postalCode | string | The postal code (or zip code in US) where the item is located. Sellers set a postal code (or zip code in US) for items when they are listed. The postal code is used for calculating proximity searches. It is anonymized when returned in itemLocation.postalCode via the API. Occurrence: Conditional |
itemSummaries.itemLocation.stateOrProvince | string | The state or province in which the item is located. Occurrence: Conditional |
itemSummaries.itemWebUrl | string | The URL to the View Item page of the item. This enables you to include a "Report Item on eBay" hyperlink that takes the buyer to the View Item page on eBay. From there they can report any issues regarding this item to eBay. Occurrence: Always |
itemSummaries.leafCategoryIds | array of string | The leaf category IDs of the item. When the item belongs to two leaf categories, the ID values are returned in the order primary, secondary. Occurrence: Always |
itemSummaries.legacyItemId | string | The unique identifier of the eBay listing that contains the item. This is the traditional/legacy ID that is often seen in the URL of the listing View Item page. Occurrence: Always |
itemSummaries.listingMarketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace where the seller listed the item. Occurrence: Always |
itemSummaries.marketingPrice | MarketingPrice | This container is returned if the item is eligible for a seller discount and contains the item's original price, and the seller discount amount and percentage. Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount | ConvertedAmount | This container returns the monetary amount of the seller discount. Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field. Occurrence: Conditional |
itemSummaries.marketingPrice.discountAmount.value | string | The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. Occurrence: Conditional |
itemSummaries.marketingPrice.discountPercentage | string | This field expresses the percentage of the seller discount based on the value in the originalPrice container. Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice | ConvertedAmount | This container returns the monetary amount of the item without the discount. Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field. Occurrence: Conditional |
itemSummaries.marketingPrice.originalPrice.value | string | The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. Occurrence: Conditional |
itemSummaries.marketingPrice.priceTreatment | PriceTreatmentEnum | Indicates the pricing treatment (discount) that was applied to the price of the item. Occurrence: Conditional |
itemSummaries.pickupOptions | array of PickupOptionSummary | This container returns the local pickup options available to the buyer. This container is only returned if the user is searching for local pickup items and set the local pickup filters in the method request. Occurrence: Conditional |
itemSummaries.pickupOptions.pickupLocationType | string | This container returns the local pickup options available to the buyer. Possible values are Occurrence: Conditional |
itemSummaries.price | ConvertedAmount | The price of the item after it has been converted into another currency.
Occurrence: Always |
itemSummaries.price.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. Occurrence: Conditional |
itemSummaries.price.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. Occurrence: Conditional |
itemSummaries.price.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field. Occurrence: Conditional |
itemSummaries.price.value | string | The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. Occurrence: Conditional |
itemSummaries.priceDisplayCondition | PriceDisplayConditionEnum | Indicates when in the buying flow the item's price can appear for minimum advertised price (MAP) items, which is the lowest price a retailer can advertise/show for this item. Occurrence: Conditional |
itemSummaries.priorityListing | boolean | This field is returned as Occurrence: Always |
itemSummaries.qualifiedPrograms | array of string | An array of the qualified programs available for the item, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION. Occurrence: Conditional |
itemSummaries.seller | Seller | This container returns basic information about the seller of the item, such as name, feedback score, etc. Occurrence: Always |
itemSummaries.seller.feedbackPercentage | string | The percentage of the total positive feedback. Occurrence: Always |
itemSummaries.seller.feedbackScore | integer | The feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller. Occurrence: Always |
itemSummaries.seller.sellerAccountType | string | 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, this value will be BUSINESS. If they register for a private account, this value will be INDIVIDUAL. This designation is required by the tax laws in some countries. Occurrence: Conditional |
itemSummaries.seller.username | string | The user name created by the seller for use on eBay. Occurrence: Always |
itemSummaries.shippingOptions | array of ShippingOptionSummary | This container returns the shipping options available to ship the item. Occurrence: Conditional |
itemSummaries.shippingOptions.guaranteedDelivery | boolean | Indicates if the seller has committed to shipping the item with eBay Guaranteed Delivery. With eBay Guaranteed Delivery, the seller is committed to getting the line item to the buyer within 4 business days or less. See the Buying items with eBay Guaranteed Delivery help topic for more details about eBay Guaranteed Delivery. Occurrence: Conditional |
itemSummaries.shippingOptions.maxEstimatedDeliveryDate | string | The end date of the delivery window (latest projected delivery date). This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer. Occurrence: Conditional |
itemSummaries.shippingOptions.minEstimatedDeliveryDate | string | The start date of the delivery window (earliest projected delivery date). This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer. Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost | ConvertedAmount | This is the estimated price to ship the item.
Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field. Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCost.value | string | The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. Occurrence: Conditional |
itemSummaries.shippingOptions.shippingCostType | string | Indicates the type of shipping used to ship the item. Possible values are Occurrence: Conditional |
itemSummaries.shortDescription | string | This text string is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.). Sometimes the title doesn't give enough information but the description is too big. Surfacing the shortDescription can often provide buyers with the additional information that could help them make a buying decision. Occurrence: Conditional |
itemSummaries.thumbnailImages | array of Image | An array of thumbnail images for the item. Occurrence: Conditional |
itemSummaries.thumbnailImages.height | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.thumbnailImages.imageUrl | string | The URL of the image. Occurrence: Always |
itemSummaries.thumbnailImages.width | integer | Reserved for future use. Occurrence: Conditional |
itemSummaries.title | string | The seller-created title of the item. Occurrence: Always |
itemSummaries.topRatedBuyingExperience | boolean | This indicates if the item is a top-rated plus item. There are three benefits of a top-rated plus item: a minimum 30-day money-back return policy, shipping the item in 1 business day with tracking provided, and the added comfort of knowing that this item is from an experienced seller with the highest buyer ratings. See the Top Rated Plus Items and Becoming a Top Rated Seller and qualifying for Top Rated Plus help topics for more information. Occurrence: Conditional |
itemSummaries.tyreLabelImageUrl | string | The URL to the image that shows the information on the tyre label. Occurrence: Conditional |
itemSummaries.unitPrice | ConvertedAmount | The price per unit for the item. Some European countries require listings for certain types of products to include the price per unit so buyers can accurately compare prices. Occurrence: Conditional |
itemSummaries.unitPrice.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. Occurrence: Conditional |
itemSummaries.unitPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. Occurrence: Conditional |
itemSummaries.unitPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field. Occurrence: Conditional |
itemSummaries.unitPrice.value | string | The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. Occurrence: Conditional |
itemSummaries.unitPricingMeasure | string | The designation, such as size, weight, volume, count, etc., that was used to specify the quantity of the item. This helps buyers compare prices. Occurrence: Conditional |
itemSummaries.watchCount | integer | The number of users that have added the item to their watch list. Occurrence: Conditional |
limit | integer | The value of the limit parameter submitted in the request, which is the maximum number of items to return on a page, from the result set. A result set is the complete set of items returned by the method. Occurrence: Always |
next | string | The URI for the next page of results. This value is returned if there is an additional page of results to return from the result set. Occurrence: Conditional |
offset | integer | This value indicates the offset used for current page of items being returned. Assume the initial request used an offset of Occurrence: Always |
prev | string | The URI for the previous page of results. This is returned if there is a previous page of results from the result set. Occurrence: Conditional |
refinement | Refinement | The container for all the search refinements. Occurrence: Conditional |
refinement.aspectDistributions | array of AspectDistribution | An array of containers for the all the aspect refinements. Occurrence: Conditional |
refinement.aspectDistributions.aspectValueDistributions | array of AspectValueDistribution | An array of containers for the various values of the aspect and the match count and a HATEOAS reference ( refinementHref) for this aspect. Occurrence: Conditional |
refinement.aspectDistributions.aspectValueDistributions.localizedAspectValue | string | The value of an aspect. For example, Red is a value for the aspect Color. Occurrence: Always |
refinement.aspectDistributions.aspectValueDistributions.matchCount | integer | The number of items with this aspect. Occurrence: Always |
refinement.aspectDistributions.aspectValueDistributions.refinementHref | string | A HATEOAS reference for this aspect. Occurrence: Always |
refinement.aspectDistributions.localizedAspectName | string | The name of an aspect, such as Brand, Color, etc. Occurrence: Conditional |
refinement.buyingOptionDistributions | array of BuyingOptionDistribution | An array of containers for the all the buying option refinements. Occurrence: Conditional |
refinement.buyingOptionDistributions.buyingOption | string | The container that returns the buying option type. This will be AUCTION, FIXED_PRICE, CLASSIFIED_AD, or a combination of these options. For details, see buyingOptions. Occurrence: Always |
refinement.buyingOptionDistributions.matchCount | integer | The number of items having this buying option. Occurrence: Always |
refinement.buyingOptionDistributions.refinementHref | string | The HATEOAS reference for this buying option. Occurrence: Always |
refinement.categoryDistributions | array of CategoryDistribution | An array of containers for the all the category refinements. Occurrence: Conditional |
refinement.categoryDistributions.categoryId | string | The identifier of the category. Occurrence: Always |
refinement.categoryDistributions.categoryName | string | The name of the category, such as Baby & Toddler Clothing. Occurrence: Always |
refinement.categoryDistributions.matchCount | integer | The number of items in this category. Occurrence: Always |
refinement.categoryDistributions.refinementHref | string | The HATEOAS reference of this category. Occurrence: Always |
refinement.conditionDistributions | array of ConditionDistribution | An array of containers for the all the condition refinements. Occurrence: Conditional |
refinement.conditionDistributions.condition | string | The text describing the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names. Occurrence: Conditional |
refinement.conditionDistributions.conditionId | string | The identifier of the condition. For example, 1000 is the identifier for NEW. Occurrence: Conditional |
refinement.conditionDistributions.matchCount | integer | The number of items having the condition. Occurrence: Always |
refinement.conditionDistributions.refinementHref | string | The HATEOAS reference of this condition. Occurrence: Always |
refinement.dominantCategoryId | string | The identifier of the category that most of the items are part of. Occurrence: Always |
total | integer | The total number of items that match the input criteria. Occurrence: Always |
warnings | array of ErrorDetailV3 | The container with all the warnings for the request. Occurrence: Conditional |
warnings.category | string | This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. Occurrence: Always |
warnings.domain | string | The name of the primary system where the error occurred. This is relevant for application errors. Occurrence: Always |
warnings.errorId | integer | A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. Occurrence: Always |
warnings.inputRefIds | array of string | An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any. Occurrence: Conditional |
warnings.longMessage | string | A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem. Occurrence: Conditional |
warnings.message | string | A description of the condition that caused the error or warning. Occurrence: Always |
warnings.outputRefIds | array of string | An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any. Occurrence: Conditional |
warnings.parameters | array of ErrorParameterV3 | An array of warning and error messages that return one or more variables contextual information about the error or warning. This is often the field or value that triggered the error or warning. Occurrence: Conditional |
warnings.parameters.name | string | This is the name of input field that caused an issue with the call request. Occurrence: Conditional |
warnings.parameters.value | string | This is the actual value that was passed in for the element specified in the name field. Occurrence: Conditional |
warnings.subdomain | string | The name of the subdomain in which the error or warning occurred. Occurrence: NA |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
Status | Meaning |
---|---|
200 | OK |
400 | Bad Request |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
12000 | API_BROWSE | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
12001 | API_BROWSE | REQUEST | The call must have a valid 'q', 'category_ids', 'epid' or 'gtin' query parameter. |
12004 | API_BROWSE | REQUEST | The 'offset' value cannot be negative. |
12005 | API_BROWSE | REQUEST | The 'offset' value must be an integer. |
12006 | API_BROWSE | REQUEST | The 'limit' value should be between 1 and 200 (inclusive). |
12007 | API_BROWSE | REQUEST | The 'limit' value must be an integer value. |
12013 | API_BROWSE | BUSINESS | Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category. |
12019 | API_BROWSE | BUSINESS | Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} . |
12020 | API_BROWSE | BUSINESS | The 'fieldgroups' value {fieldgroups} is invalid when multiple 'category_ids' are specified. Either change the call to have only one value in 'category_ids' or remove the 'fieldgroups'. |
12023 | API_BROWSE | REQUEST | This keyword search results in a response that is too large to return. Either change the keyword or add additional query parameters and/or filters. |
12025 | API_BROWSE | REQUEST | The 'charity_ids' field has exceeded the maximum limit of 20. |
12026 | API_BROWSE | REQUEST | The 'charity_ids' field is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}. |
12027 | API_BROWSE | REQUEST | The 'auto_correct' value is invalid. For the valid values, refer to the API call documentation. |
12028 | API_BROWSE | REQUEST | The 'auto_correct' is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12029 | API_BROWSE | REQUEST | The maximum number of listings that can be retrieved is 10,000, so your offset value must be less than 10,000. If 10,000 or more listings are matching your search criteria, consider narrowing the scope of your search. |
12030 | API_BROWSE | REQUEST | The number of categories in the request has exceeded the limit. Please reduce the number of categories to {allowedMaxCategories} or less. |
12032 | API_BROWSE | REQUEST | The number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to 250 or fewer. |
12033 | API_BROWSE | REQUEST | The 'qualifiedPrograms' filter for {filterValue} requires valid 'deliveryPostalCode' and 'deliveryCountry' filter values. |
12034 | API_BROWSE | REQUEST | The 'buyingOptions' filter value {filterValue} is not supported for the sort by {sortOption}. For the supported values, refer to the API call documentation. |
12503 | API_BROWSE | REQUEST | There is no compatibility information found either because there is no compatibility results or the data provided in the compatibility_filter is invalid or insufficient. |
12504 | API_BROWSE | REQUEST | You must provide a category ID that supports fitment. |
12505 | API_BROWSE | REQUEST | The following compatibility attributes in the request are not supported: {attributes}. |
12506 | API_BROWSE | REQUEST | The category ID submitted does not support fitment. |
12507 | API_BROWSE | REQUEST | To filter by 'guaranteedDeliveryInDays', you must include 'deliveryCountry'. |
12508 | API_BROWSE | REQUEST | To filter by 'guaranteedDeliveryInDays', you must include 'deliveryPostalCode' for the 'deliveryCountry'. |
12509 | API_BROWSE | REQUEST | The 'guaranteedDeliveryInDays' value {guaranteedDeliveryInDays} is invalid for 'deliveryCountry' value {deliveryCountry}. Valid values for 'guaranteedDeliveryInDays' for {deliveryCountry} must be in the range of {rangeLowerBound} to {rangeUpperBound} inclusive. |
12510 | API_BROWSE | REQUEST | The 'guaranteedDeliveryInDays' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12512 | API_BROWSE | REQUEST | The 'qualifiedPrograms' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12513 | API_BROWSE | BUSINESS | The 'priorityListing' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12514 | API_BROWSE | BUSINESS | The 'priorityListing' filter is not supported for the specified sort option. Refer to the API call documentation. |
12515 | API_BROWSE | REQUEST | The 'offset' value must be either zero or a multiple of the 'limit' value. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
12002 | API_BROWSE | REQUEST | The {filterName} value is invalid. For the valid values, refer to the API call documentation. |
12003 | API_BROWSE | REQUEST | A seller 'username' provided in the request filters is invalid. |
12008 | API_BROWSE | REQUEST | The 'sort' value is invalid. For the valid values, refer to the API call documentation. |
12009 | API_BROWSE | REQUEST | The 'category_ids' query parameter is invalid. |
12010 | API_BROWSE | REQUEST | There are four filters required for local pickup. 'pickupPostalCode','pickupCountry','pickupRadiusUnit','pickupRadius'. One or more is missing or invalid. |
12011 | API_BROWSE | REQUEST | 'deliveryCountry' is a mandatory filter to provide a delivery location. 'deliveryPostalCode' is optional. |
12012 | API_BROWSE | REQUEST | A valid 'price' filter and a valid 'priceCurrency' filter is necessary to filter based on price. |
12014 | API_BROWSE | BUSINESS | The 'sellerAccountTypes' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces} |
12015 | API_BROWSE | REQUEST | The postal code filter value is invalid for the specified country and this filter was ignored. |
12016 | API_BROWSE | REQUEST | The 'fieldgroups' value {fieldgroups} is invalid. For the valid values, refer to the API call reference documentation |
12017 | API_BROWSE | REQUEST | The 'aspect_filter' query parameter must include a categoryId. For information, see the API call reference documentation. |
12018 | API_BROWSE | REQUEST | The {aspectFilter} aspect_filter value is invalid. For information, see the API call reference documentation. |
12021 | API_BROWSE | REQUEST | The 'epid' value {epid} is invalid. For information, see the API call reference documentation. |
12022 | API_BROWSE | REQUEST | The 'gtin' value {gtin} is invalid. For information, see the API call reference documentation. |
12024 | API_BROWSE | REQUEST | The 'charity_ids' value {charity_id} is invalid. For more information see the API call reference documentation. |
12502 | API_BROWSE | REQUEST | The {compatibilityFilter} compatibility_filter is invalid. For information, see the API call reference documentation. |
12511 | API_BROWSE | REQUEST | Either 'deliveryCountry' or 'deliveryPostalCode' is invalid, hence 'guaranteedDeliveryInDays' filter was ignored. |
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Search for Items by Keyword
This sample returns a set of eBay items that match the keyword.
Input
The inputs are limit and q, which is the keyword, URI parameters. There is no payload with this request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=3
Output
If the call is successful, 3 items per set will be returned.
Sample 2: Search for Items by Category
This sample searches for items in the Soccer Balls category.
Input
The inputs are category_ids, limit, and offset URI parameters. There is no payload with this request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?category_ids=20863&limit=3&offset=9
Output
If the call is successful, soccer balls are returned. Since limit=3 and offset=9 were specified, and the offset specified is a multiple of the limit, the fourth page containing items 10 through 12 (of the total 16987 items) was returned.
Sample 3: Refine Keyword Results by Category
Using a category ID with a keyword gives you additional control over the result set. For example, let's say you are looking of a toy phone. If you search for "phone", the result set will be mobile phones because this is the "Best Match" for this search. But if you also include the toy category ID, the results will be what you wanted.
Input
The inputs are q and categoryIds URI parameters. There is no payload with this request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=phone&category_ids=220&limit=3
Output
If the call is successful, toy phones are returned.
Sample 4: Retrieve the Item Aspects by Keyword Search
This call searches for drones. Based on the results of that search, it returns the dominant category ID, which is the category most of the items are in and the aspect refinements for this category.
Input
The inputs are q and fieldgroups=ASPECT_REFINEMENTS URI parameters. There is no payload with this request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&fieldgroups=ASPECT_REFINEMENTS
Output
If the call is successful, the dominantCategoryId field, which we will use in the next sample, and the aspectDistributions container are returned.
Sample 5: Return All Refinements For a Category
This call retrieves all the refinements for the category submitted. We used the category ID returned by the previous sample in the dominantCategoryId field.
If you wanted to return the refinement and the items, you would replace fieldgroups=ASPECT_REFINEMENTS,CATEGORY_REFINEMENTS,CONDITION_REFINEMENTS,BUYING_OPTION_REFINEMENTS
fieldgroups=FULL
.
Input
The inputs are q and fieldgroups URI parameters. There is no payload with this request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=3&category_ids=179697&fieldgroups=ASPECT_REFINEMENTS,CATEGORY_REFINEMENTS,CONDITION_REFINEMENTS,BUYING_OPTION_REFINEMENTS
Output
If the call is successful, the dominantCategoryId field is return, which is the category that was submitted in the call. The categoryDistributions container is return, which shows the category name. The conditionDistributions buyingOptionDistributions aspectDistributions containers are returned, which contain all the refinements for the category. You can use response from this call to create a histogram for this category, which gives your shoppers the ability to browse the items and further refine the results.
Sample 6: Filter the Keyword Results by Item Aspects
This call searches for drones and returns only the items within the category and the item aspects specified. Because fieldgroups is set to EXTENDED it also returns the shortDescription and itemLocation.city fields.
Input
The inputs are q, category_ids, fieldgroups and aspect_filter URI parameters. There is no payload with this request.
Note: As with all query
parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about
encoding request parameters, see URL encoding query parameter values.
The first line of the response is the encoded request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&category_ids=179697&limit=3&fieldgroups=EXTENDED,MATCHING_ITEMS&aspect_filter=categoryId:179697,conditionDistributions:{NEW},Connectivity:{App Controller},Camera Integration:{Camera Included},Type:{Ready to Fly Drone}
Output
If the call is successful, a paged collection of items matching the criteria are returned.
Sample 7: Return Items with Free Shipping
This call searches for drones and returns only the items that offer free shipping.
Input
The inputs are q and filter=maxDeliveryCost URI parameters. There is no payload with this request.
Note: As with all query
parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about
encoding request parameters, see URL encoding query parameter values.
The first line of the response is the encoded request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=3&filter=maxDeliveryCost:0
Output
If the call is successful, three items that have free shipping (shippingOptions.shippingCost.value
is 0) are returned.
Sample 8: Return Items Based on Price and Condition
This call searches for new iPhones within a price range.
Input
The inputs are q and the price, priceCurrency, and conditions, filter URI parameters. There is no payload with this request.
Note: As with all query
parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about
encoding request parameters, see URL encoding query parameter values.
The first line of the response is the encoded request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=5&filter=price:[300..800],priceCurrency:USD,conditions:{NEW}
Output
If the call is successful, the items meeting the criteria are returned.
Sample 9: Return Items Associated with a Charity
This call searches for items that are associated with the Toys for Tots charity.
Input
The inputs are q, charity_ids and limit.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?charity_ids=203021444&limit=2
Output
If the call is successful, the items meeting the criteria are returned.
Sample 10: Return Items that are Compatible with the Keyword and Vehicle
This call searches for brakes that are compatible with a 2018 BMW 318i.
Input
The inputs are q, category_ids, compatibility_filter, and limit. In order to get the best results, all the product attributes for the vehicle are specified; Make, Model, Year, Trim, and Engine.
Note: As with all query
parameter values, the filter parameters must be URL encoded. But for readability in the request below, the encoding has been omitted. For more information about
encoding request parameters, see URL encoding query parameter values.
The first line of the response is the encoded request.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=brakes&category_ids=33559&compatibility_filter=Year:2018;Make:BMW;Model:318i;Trim:Executive Sedan 4-Door;Engine:1.5L 1499CC l3 GAS DOHC Turbocharged&limit=3
Output
If the call is successful, the items meeting the criteria are returned. The attributes that are compatible are
returned in the compatibilityProperties container and the compatibilityMatch field tells you how well
the item matches this vehicle.
In this example, all the items returned are an "exact" match.
Sample 11: Return Items Based on Auto-Corrected Keyword
This call searches for an item with a misspelled keyword.
Input
The inputs are q, auto_correct, and limit.
GEThttps://api.ebay.com/buy/browse/v1/item_summary/search?q=macbok&auto_correct=KEYWORD&limit=4
Output
If the call is successful, the items meeting the criteria for the auto-corrected keyword are returned.