Skip to main content

POST/item_summary/search_by_image

Note: Experimental Method This is an experimental method that is available to select developers approved by business units. For information on how to obtain access to this API in production, see the Buy APIs Requirements.

This method searches for eBay items based on a image and retrieves summaries of the items. You pass in a Base64 image in the request payload and can refine the search by category, or eBay product ID (ePID), or a combination of these using URI parameters.

To get the Base64 image string, you can use sites such as https://codebeautify.org/image-to-base64-converter.

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.
  • Filtering by item aspects using the aspect_filter parameter.

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.

URL Encoding for Parameters

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.

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 the itemAffiliateWebUrl field to forward your buyer to the ebay.com site.

Input

Resource URI

This method is not supported in Sandbox environment.

URI parameters

ParameterTypeDescription
charity_idsarray of stringThe 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".
  • To find the charities eBay supports, you can search for a charity at Charity Search or go to Charity Shop.
  • To find the charity ID of a specific charity, click on a charity and use the EIN number. For example, the charity ID for American Red Cross, is 530196605.
You can also use any combination of the 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

fieldgroupsarray of stringThis 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:
  • ASPECT_REFINEMENTS - This returns the aspectDistributions container, which has the dominantCategoryId, matchCount, and refinementHref for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be Model Year, Exterior Color, Vehicle Mileage, etc.

    Note: ASPECT_REFINEMENTS are category specific.
  • BUYING_OPTION_REFINEMENTS - This returns the buyingOptionDistributions container, which has the matchCount and refinementHref for AUCTION, FIXED_PRICE (Buy It Now), and CLASSIFIED_AD items.
  • CATEGORY_REFINEMENTS - This returns the categoryDistributions container, which has the categories that the item is in.
  • CONDITION_REFINEMENTS - This returns the conditionDistributions container, such as NEW, USED, etc. Within these groups are multiple states of the condition. For example, New can be New without tag, New in box, New without box, etc.
  • EXTENDED - This returns the shortDescription field, which provides condition and item aspect information and the itemLocation.city field.
  • MATCHING_ITEMS - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.
  • FULL - This returns all the refinement containers and all the matching items.
Code so that your app gracefully handles any future changes to this list.

Default: MATCHING_ITEMS

Occurrence: Optional

category_idsarray of stringThe category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs.

Note: Currently, you can pass in only one category ID per request.

You can also use any combination of the category_Ids and epid fields. This gives you additional control over the result set.

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:
  • Use the Category Changes page.
  • Use the Taxonomy API. For details see Get Categories for Buy APIs.
  • Submit the following method to get the dominantCategoryId for an item.
    /buy/browse/v1/item_summary/search?q= keyword&fieldgroups=ASPECT_REFINEMENTS
Required: The method must have category_ids or epid (or any combination of these)

Occurrence: Optional

filterarray of FilterFieldAn 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

sortarray of SortFieldThe 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:
  • sort=distance - This sorts by distance in ascending order (shortest distance first). This sorting option is only applicable if the pickup filters are used, and only ascending order is supported.
  • sort=-price - This sorts by price + shipping cost in descending order (highest price first). This sorting option (by price) is only guaranteed to work correctly if the X-EBAY-C-ENDUSERCTX request header is used, with the contextualLocation parameter being used to set the delivery country and postal code. Here is an example of how this header would be used to do this (note the URL encoding):

    X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406
  • sort=newlyListed - This sorts by listing date (most recently listed/newest items first).
  • sort=endingSoonest - This sorts by date/time the listing ends (listings nearest to end date/time first).
Default: Ascending

Occurrence: Optional

limitstringThe 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

offsetstringSpecifies 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_filterAspectFilterThis 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.

category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}

Required: The category ID is required twice; once as a URI parameter and as part of the aspect_filter.

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.

HeaderTypeDescription
Content-TypestringThis header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

X-EBAY-C-ENDUSERCTXstringThis 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-IDstringThis 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: Strongly Recommended

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

Copy complete valid JSON to clipboard

Request fields

Input container/fieldTypeDescription
imagestring

The Base64 string of the image.

Occurrence: Required

Output

HTTP response headers

This call has no response headers.

Response payload

{ /* SearchPagedCollection<ItemSummary> */
"autoCorrections" :
{ /* AutoCorrections */
"q" : "string"
},
"href" : "string",
"itemSummaries" : [
{ /* ItemSummary */
"additionalImages" : [
{ /* Image */
"height" : "integer",
"imageUrl" : "string",
"width" : "integer"
}
],
"adultOnly" : "boolean",
"availableCoupons" : "boolean",
"bidCount" : "integer",
"buyingOptions" : [
"string"
],
"categories" : [
{ /* Category */
"categoryId" : "string",
"categoryName" : "string"
}
],
"compatibilityMatch" : "CompatibilityMatchEnum : [EXACT,POSSIBLE]",
"compatibilityProperties" : [
{ /* CompatibilityProperty */
"localizedName" : "string",
"name" : "string",
"value" : "string"
}
],
"condition" : "string",
"conditionId" : "string",
"currentBidPrice" :
{ /* ConvertedAmount */
"convertedFromCurrency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"convertedFromValue" : "string",
"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"value" : "string"
},
"distanceFromPickupLocation" :
{ /* TargetLocation */
"unitOfMeasure" : "string",
"value" : "string"
},
"energyEfficiencyClass" : "string",
"epid" : "string",
"image" :
{ /* Image */
"height" : "integer",
"imageUrl" : "string",
"width" : "integer"
},
"itemAffiliateWebUrl" : "string",
"itemCreationDate" : "string",
"itemEndDate" : "string",
"itemGroupHref" : "string",
"itemGroupType" : "string",
"itemHref" : "string",
"itemId" : "string",
"itemLocation" :
{ /* ItemLocationImpl */
"addressLine1" : "string",
"addressLine2" : "string",
"city" : "string",
"country" : "CountryCodeEnum : [AD,AE,AF...]",
"county" : "string",
"postalCode" : "string",
"stateOrProvince" : "string"
},
"itemWebUrl" : "string",
"leafCategoryIds" : [
"string"
],
"legacyItemId" : "string",
"listingMarketplaceId" : "MarketplaceIdEnum : [EBAY_AU,EBAY_AT,EBAY_BE...]",
"marketingPrice" :
{ /* MarketingPrice */
"discountAmount" :
{ /* ConvertedAmount */
"convertedFromCurrency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"convertedFromValue" : "string",
"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"value" : "string"
},
"discountPercentage" : "string",
"originalPrice" :
{ /* ConvertedAmount */
"convertedFromCurrency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"convertedFromValue" : "string",
"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"value" : "string"
},
"priceTreatment" : "PriceTreatmentEnum : [MINIMUM_ADVERTISED_PRICE,LIST_PRICE,MARKDOWN]"
},
"pickupOptions" : [
{ /* PickupOptionSummary */
"pickupLocationType" : "string"
}
],
"price" :
{ /* ConvertedAmount */
"convertedFromCurrency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"convertedFromValue" : "string",
"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"value" : "string"
},
"priceDisplayCondition" : "PriceDisplayConditionEnum : [ONLY_SHOW_WHEN_ADDED_IN_CART,ONLY_SHOW_ON_REQUEST,ALWAYS_SHOW]",
"priorityListing" : "boolean",
"qualifiedPrograms" : [
"string"
],
"seller" :
{ /* Seller */
"feedbackPercentage" : "string",
"feedbackScore" : "integer",
"sellerAccountType" : "string",
"username" : "string"
},
"shippingOptions" : [
{ /* ShippingOptionSummary */
"guaranteedDelivery" : "boolean",
"maxEstimatedDeliveryDate" : "string",
"minEstimatedDeliveryDate" : "string",
"shippingCost" :
{ /* ConvertedAmount */
"convertedFromCurrency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"convertedFromValue" : "string",
"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"value" : "string"
},
"shippingCostType" : "string"
}
],
"shortDescription" : "string",
"thumbnailImages" : [
{ /* Image */
"height" : "integer",
"imageUrl" : "string",
"width" : "integer"
}
],
"title" : "string",
"topRatedBuyingExperience" : "boolean",
"tyreLabelImageUrl" : "string",
"unitPrice" :
{ /* ConvertedAmount */
"convertedFromCurrency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"convertedFromValue" : "string",
"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"value" : "string"
},
"unitPricingMeasure" : "string",
"watchCount" : "integer"
}
],
"limit" : "integer",
"next" : "string",
"offset" : "integer",
"prev" : "string",
"refinement" :
{ /* Refinement */
"aspectDistributions" : [
{ /* AspectDistribution */
"aspectValueDistributions" : [
{ /* AspectValueDistribution */
"localizedAspectValue" : "string",
"matchCount" : "integer",
"refinementHref" : "string"
}
],
"localizedAspectName" : "string"
}
],
"buyingOptionDistributions" : [
{ /* BuyingOptionDistribution */
"buyingOption" : "string",
"matchCount" : "integer",
"refinementHref" : "string"
}
],
"categoryDistributions" : [
{ /* CategoryDistribution */
"categoryId" : "string",
"categoryName" : "string",
"matchCount" : "integer",
"refinementHref" : "string"
}
],
"conditionDistributions" : [
{ /* ConditionDistribution */
"condition" : "string",
"conditionId" : "string",
"matchCount" : "integer",
"refinementHref" : "string"
}
],
"dominantCategoryId" : "string"
},
"total" : "integer",
"warnings" : [
{ /* ErrorDetailV3 */
"category" : "string",
"domain" : "string",
"errorId" : "integer",
"inputRefIds" : [
"string"
],
"longMessage" : "string",
"message" : "string",
"outputRefIds" : [
"string"
],
"parameters" : [
{ /* ErrorParameterV3 */
"name" : "string",
"value" : "string"
}
],
"subdomain" : "string"
}
]
}

Response fields

Output container/fieldTypeDescription
autoCorrectionsAutoCorrections

The auto-corrected inputs.

Occurrence: Conditional

autoCorrections.qstring

The automatically spell-corrected keyword from the request.

Occurrence: Conditional

hrefstring

The URI of the current page of results.

The following example of the search method returns items 1 thru 5 from the list of items found.

https://api.ebay.com/buy/v1/item_summary/search?q=shirt&limit=5&offset=0.

Occurrence: Always

itemSummariesarray of ItemSummary

An array of the items on this page. The items are sorted according to the sorting method specified in the request.

Occurrence: Conditional

itemSummaries.additionalImagesarray 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.heightinteger

Reserved for future use.

Occurrence: Conditional

itemSummaries.additionalImages.imageUrlstring

The URL of the image.

Occurrence: Always

itemSummaries.additionalImages.widthinteger

Reserved for future use.

Occurrence: Conditional

itemSummaries.adultOnlyboolean

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

This boolean attribute indicates if coupons are available for the item.

Occurrence: Always

itemSummaries.bidCountinteger

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.buyingOptionsarray of string

A comma separated list of all the purchase options available for the item.

Values Returned:

  • FIXED_PRICE - Indicates the buyer can purchase the item for a set price using the Buy It Now button.
  • AUCTION - Indicates the buyer can place a bid for the item. After the first bid is placed, this becomes a live auction item and is the only buying option for this item.
  • 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.
  • CLASSIFIED_AD - Indicates that the final sales transaction is to be completed outside of the eBay environment.
Code so that your app gracefully handles any future changes to this list.

Occurrence: Always

itemSummaries.categoriesarray 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.categoryIdstring

The unique identifier of the category.

Occurrence: Always

itemSummaries.categories.categoryNamestring

The name of the category.

Occurrence: Conditional

itemSummaries.compatibilityMatchCompatibilityMatchEnum

This indicates how well the item matches the compatibility_filter product attributes.

Valid Values: EXACT or POSSIBLE

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

itemSummaries.compatibilityPropertiesarray 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.localizedNamestring

The name of the product attribute that as been translated to the language of the site.

Occurrence: Conditional

itemSummaries.compatibilityProperties.namestring

The name of the product attribute, such as Make, Model, Year, etc.

Occurrence: Conditional

itemSummaries.compatibilityProperties.valuestring

The value for the name attribute, such as BMW, R1200GS, 2011, etc.

Occurrence: Conditional

itemSummaries.conditionstring

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.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

itemSummaries.conditionIdstring

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.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

itemSummaries.currentBidPriceConvertedAmount

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

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

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

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.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

itemSummaries.currentBidPrice.valuestring

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

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

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 mi or km.

Occurrence: Conditional

itemSummaries.distanceFromPickupLocation.valuestring

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

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.

Currently, this field is only applicable for the Germany site, and is only returned if the seller specified the energy efficiency rating through item specifics at listing time. Rating values include A+++, A++, A+, A, B, C, D, E, F, and G.

Occurrence: Conditional

itemSummaries.epidstring

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

The URL to the primary image of the item.

Occurrence: Always

itemSummaries.image.heightinteger

Reserved for future use.

Occurrence: Conditional

itemSummaries.image.imageUrlstring

The URL of the image.

Occurrence: Always

itemSummaries.image.widthinteger

Reserved for future use.

Occurrence: Conditional

itemSummaries.itemAffiliateWebUrlstring

The URL to the View Item page of the item which includes the affiliate tracking ID.

Note: In order to receive commissions on sales, eBay Partner Network affiliates must use this URL to forward buyers to the listing on the eBay marketplace.
The itemAffiliateWebUrl is only returned if:

  • The marketplace through which the item is being viewed is part of the eBay Partner Network. Currently Poland (EBAY_PL) and Singapore (EBAY_SG) are not supported.

    For additional information, refer to eBay Partner Network.
  • The seller enables affiliate tracking for the item by including the X-EBAY-C-ENDUSERCTX request header in the method.

Occurrence: Conditional

itemSummaries.itemCreationDatestring

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

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.

Note: This field is not returned for Good 'Til Cancelled (GTC) listings.

Occurrence: Conditional

itemSummaries.itemGroupHrefstring

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.

Note: This field is returned only for item groups.

Occurrence: Conditional

itemSummaries.itemGroupTypestring

The indicates the item group type. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Currently only the SELLER_DEFINED_VARIATIONS is supported and indicates this is an item group created by the seller.

Note: This field is returned only for item groups.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

itemSummaries.itemHrefstring

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

The unique RESTful identifier of the item.

Occurrence: Always

itemSummaries.itemLocationItemLocationImpl

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

The first line of the street address.

Occurrence: Conditional

itemSummaries.itemLocation.addressLine2string

The second line of the street address. This field may contain such values as an apartment or suite number.

Occurrence: Conditional

itemSummaries.itemLocation.citystring

The city in which the item is located.

Restriction: This field is populated in the search method response only when fieldgroups = EXTENDED.

Occurrence: Conditional

itemSummaries.itemLocation.countryCountryCodeEnum

The two-letter ISO 3166 standard code that indicates the country in which the item is located.

Occurrence: Always

itemSummaries.itemLocation.countystring

The county in which the item is located.

Occurrence: Conditional

itemSummaries.itemLocation.postalCodestring

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

The state or province in which the item is located.

Occurrence: Conditional

itemSummaries.itemWebUrlstring

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.leafCategoryIdsarray 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.legacyItemIdstring

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

The ID of the eBay marketplace where the seller listed the item.

Occurrence: Always

itemSummaries.marketingPriceMarketingPrice

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

This container returns the monetary amount of the seller discount.

Occurrence: Conditional

itemSummaries.marketingPrice.discountAmount.convertedFromCurrencyCurrencyCodeEnum

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

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

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.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

itemSummaries.marketingPrice.discountAmount.valuestring

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

This field expresses the percentage of the seller discount based on the value in the originalPrice container.

Occurrence: Conditional

itemSummaries.marketingPrice.originalPriceConvertedAmount

This container returns the monetary amount of the item without the discount.

Occurrence: Conditional

itemSummaries.marketingPrice.originalPrice.convertedFromCurrencyCurrencyCodeEnum

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

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

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.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

itemSummaries.marketingPrice.originalPrice.valuestring

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

Indicates the pricing treatment (discount) that was applied to the price of the item.

Note: The pricing treatment affects the way and where the discounted price can be displayed.

Occurrence: Conditional

itemSummaries.pickupOptionsarray 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.pickupLocationTypestring

This container returns the local pickup options available to the buyer. Possible values are ARRANGED_LOCATION and STORE.

Occurrence: Conditional

itemSummaries.priceConvertedAmount

The price of the item after it has been converted into another currency.

The price includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must do one or more of the following to see VAT-inclusive pricing:

  • Pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB)
  • Pass the contextualLocation values for the supported marketplace in the X-EBAY-C-ENDUSERCTX request header
  • Specify the supported marketplace using the deliveryCountry filter URI parameter (such as filter=deliveryCountry:GB)
Note: For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

itemSummaries.price.convertedFromCurrencyCurrencyCodeEnum

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

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

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.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

itemSummaries.price.valuestring

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

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

This field is returned as true if the listing is part of a Promoted Listing campaign. Promoted Listings are available to Above Standard and Top Rated sellers with recent sales activity.

Note: Priority Listing is returned only with a Best Match sort and will not be returned for other sort options.

Occurrence: Always

itemSummaries.qualifiedProgramsarray of string

An array of the qualified programs available for the item, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION.

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

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

Occurrence: Conditional

itemSummaries.sellerSeller

This container returns basic information about the seller of the item, such as name, feedback score, etc.

Occurrence: Always

itemSummaries.seller.feedbackPercentagestring

The percentage of the total positive feedback.

Occurrence: Always

itemSummaries.seller.feedbackScoreinteger

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

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.

This field is returned only on the following sites.

EBAY_AT, EBAY_BE, EBAY_CH, EBAY_DE, EBAY_ES, EBAY_FR, EBAY_GB, EBAY_IE, EBAY_IT, EBAY_PL

Valid Values: BUSINESS or INDIVIDUAL

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

itemSummaries.seller.usernamestring

The user name created by the seller for use on eBay.

Occurrence: Always

itemSummaries.shippingOptionsarray of ShippingOptionSummary

This container returns the shipping options available to ship the item.

Occurrence: Conditional

itemSummaries.shippingOptions.guaranteedDeliveryboolean

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

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.

Note: For the best accuracy, always include the contextualLocation values in the X-EBAY-C-ENDUSERCTX request header.

Occurrence: Conditional

itemSummaries.shippingOptions.minEstimatedDeliveryDatestring

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.

Note: For the best accuracy, always include the contextualLocation values in the X-EBAY-C-ENDUSERCTX request header.

Occurrence: Conditional

itemSummaries.shippingOptions.shippingCostConvertedAmount

This is the estimated price to ship the item.

The price includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must do one or more of the following to see VAT-inclusive pricing:

  • Pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB)
  • Pass the contextualLocation values for the supported marketplace in the X-EBAY-C-ENDUSERCTX request header
  • Specify the supported marketplace using the deliveryCountry filter URI parameter (such as filter=deliveryCountry:GB)
Note: For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Conditional

itemSummaries.shippingOptions.shippingCost.convertedFromCurrencyCurrencyCodeEnum

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

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

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.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

itemSummaries.shippingOptions.shippingCost.valuestring

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

Indicates the type of shipping used to ship the item. Possible values are FIXED (flat-rate shipping) and CALCULATED (shipping cost calculated based on item and buyer location).

Occurrence: Conditional

itemSummaries.shortDescriptionstring

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.

For example:

" title": "Petrel U42W FPV Drone RC Quadcopter w/HD Camera Live Video One Key Off / Landing",
"shortDescription": "1 U42W Quadcopter. Syma X5SW-V3 Wifi FPV RC Drone Quadcopter 2.4Ghz 6-Axis Gyro with Headless Mode. Syma X20 Pocket Drone 2.4Ghz Mini RC Quadcopter Headless Mode Altitude Hold. One Key Take Off / Landing function: allow beginner to easy to fly the drone without any skill.",

Restriction: This field is returned by the search method only when fieldgroups = EXTENDED.

Occurrence: Conditional

itemSummaries.thumbnailImagesarray of Image

An array of thumbnail images for the item.

Occurrence: Conditional

itemSummaries.thumbnailImages.heightinteger

Reserved for future use.

Occurrence: Conditional

itemSummaries.thumbnailImages.imageUrlstring

The URL of the image.

Occurrence: Always

itemSummaries.thumbnailImages.widthinteger

Reserved for future use.

Occurrence: Conditional

itemSummaries.titlestring

The seller-created title of the item.

Maximum Length: 80 characters

Occurrence: Always

itemSummaries.topRatedBuyingExperienceboolean

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

The URL to the image that shows the information on the tyre label.

Occurrence: Conditional

itemSummaries.unitPriceConvertedAmount

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.

For example:

"unitPricingMeasure": "100g",
"unitPrice": {
  "value": "7.99",
  "currency": "GBP"

Occurrence: Conditional

itemSummaries.unitPrice.convertedFromCurrencyCurrencyCodeEnum

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

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

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.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

itemSummaries.unitPrice.valuestring

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

The designation, such as size, weight, volume, count, etc., that was used to specify the quantity of the item. This helps buyers compare prices.

For example, the following tells the buyer that the item is 7.99 per 100 grams.

"unitPricingMeasure": "100g",
"unitPrice": {
  "value": "7.99",
  "currency": "GBP"

Occurrence: Conditional

itemSummaries.watchCountinteger

The number of users that have added the item to their watch list.

Note: This field is restricted to applications that have been granted permission to access this feature. You must submit an App Check ticket to request this access. In the App Check form, add a note to the Application Title/Summary and/or Application Details fields that you want access to Watch Count data in the Browse API.

Occurrence: Conditional

limitinteger

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

nextstring

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.

The following example of the search method returns items 5 thru 10 from the list of items found.

https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=10

Occurrence: Conditional

offsetinteger

This value indicates the offset used for current page of items being returned. Assume the initial request used an offset of 0 and a limit of 3. Then in the first page of results, this value would be 0, and items 1-3 are returned. For the second page, this value is 3 and so on.

Occurrence: Always

prevstring

The URI for the previous page of results. This is returned if there is a previous page of results from the result set.

The following example of the search method returns items 1 thru 5 from the list of items found, which would be the first set of items returned.

https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=0

Occurrence: Conditional

refinementRefinement

The container for all the search refinements.

Occurrence: Conditional

refinement.aspectDistributionsarray of AspectDistribution

An array of containers for the all the aspect refinements.

Occurrence: Conditional

refinement.aspectDistributions.aspectValueDistributionsarray 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.localizedAspectValuestring

The value of an aspect. For example, Red is a value for the aspect Color.

Occurrence: Always

refinement.aspectDistributions.aspectValueDistributions.matchCountinteger

The number of items with this aspect.

Occurrence: Always

refinement.aspectDistributions.aspectValueDistributions.refinementHrefstring

A HATEOAS reference for this aspect.

Occurrence: Always

refinement.aspectDistributions.localizedAspectNamestring

The name of an aspect, such as Brand, Color, etc.

Occurrence: Conditional

refinement.buyingOptionDistributionsarray of BuyingOptionDistribution

An array of containers for the all the buying option refinements.

Occurrence: Conditional

refinement.buyingOptionDistributions.buyingOptionstring

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

The number of items having this buying option.

Occurrence: Always

refinement.buyingOptionDistributions.refinementHrefstring

The HATEOAS reference for this buying option.

Occurrence: Always

refinement.categoryDistributionsarray of CategoryDistribution

An array of containers for the all the category refinements.

Occurrence: Conditional

refinement.categoryDistributions.categoryIdstring

The identifier of the category.

Occurrence: Always

refinement.categoryDistributions.categoryNamestring

The name of the category, such as Baby & Toddler Clothing.

Occurrence: Always

refinement.categoryDistributions.matchCountinteger

The number of items in this category.

Occurrence: Always

refinement.categoryDistributions.refinementHrefstring

The HATEOAS reference of this category.

Occurrence: Always

refinement.conditionDistributionsarray of ConditionDistribution

An array of containers for the all the condition refinements.

Occurrence: Conditional

refinement.conditionDistributions.conditionstring

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.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

refinement.conditionDistributions.conditionIdstring

The identifier of the condition. For example, 1000 is the identifier for NEW.

Occurrence: Conditional

refinement.conditionDistributions.matchCountinteger

The number of items having the condition.

Occurrence: Always

refinement.conditionDistributions.refinementHrefstring

The HATEOAS reference of this condition.

Occurrence: Always

refinement.dominantCategoryIdstring

The identifier of the category that most of the items are part of.

Occurrence: Always

totalinteger

The total number of items that match the input criteria.

Note: total is just an indicator of the number of listings for a given query. It could vary based on the number of listings with variations included in the result. It is strongly recommended that total not be used in pagination use cases. Instead, use next to determine the results on the next page.

Occurrence: Always

warningsarray of ErrorDetailV3

The container with all the warnings for the request.

Occurrence: Conditional

warnings.categorystring

This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Always

warnings.domainstring

The name of the primary system where the error occurred. This is relevant for application errors.

Occurrence: Always

warnings.errorIdinteger

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.inputRefIdsarray 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.longMessagestring

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

A description of the condition that caused the error or warning.

Occurrence: Always

warnings.outputRefIdsarray 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.parametersarray 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.namestring

This is the name of input field that caused an issue with the call request.

Occurrence: Conditional

warnings.parameters.valuestring

This is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstring

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.

StatusMeaning
200OK
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
12000API_BROWSEAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
12004API_BROWSEREQUESTThe 'offset' value cannot be negative.
12005API_BROWSEREQUESTThe 'offset' value must be an integer.
12006API_BROWSEREQUESTThe 'limit' value should be between 1 and 200 (inclusive).
12007API_BROWSEREQUESTThe 'limit' value must be an integer value.
12013API_BROWSEBUSINESSTop level category browsing is not allowed. Please provide keywords or more filters for the applied top level category.
12019API_BROWSEBUSINESSCurrently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .
12020API_BROWSEBUSINESSThe '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'.
12025API_BROWSEREQUESTThe 'charity_ids' field has exceeded the maximum limit of 20.
12026API_BROWSEREQUESTThe 'charity_ids' field is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}.
12029API_BROWSEREQUESTThe 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.
12030API_BROWSEREQUESTThe number of categories in the request has exceeded the limit. Please reduce the number of categories to {allowedMaxCategories} or less.
12032API_BROWSEREQUESTThe number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to 250 or fewer.
12033API_BROWSEREQUESTThe 'qualifiedPrograms' filter for {filterValue} requires valid 'deliveryPostalCode' and 'deliveryCountry' filter values.
12034API_BROWSEREQUESTThe 'buyingOptions' filter value {filterValue} is not supported for the sort by {sortOption}. For the supported values, refer to the API call documentation.
12500API_BROWSEREQUESTThis image search results in a response that is too large to return. Either change the image or add additional query parameters and/or filters.
12501API_BROWSEREQUESTThe image data is empty, is not Base64 encoded, or is invalid.
12507API_BROWSEREQUESTTo filter by 'guaranteedDeliveryInDays', you must include 'deliveryCountry'.
12508API_BROWSEREQUESTTo filter by 'guaranteedDeliveryInDays', you must include 'deliveryPostalCode' for the 'deliveryCountry'.
12509API_BROWSEREQUESTThe '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.
12510API_BROWSEREQUESTThe 'guaranteedDeliveryInDays' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}
12512API_BROWSEREQUESTThe 'qualifiedPrograms' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}
12513API_BROWSEBUSINESSThe 'priorityListing' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}
12514API_BROWSEBUSINESSThe 'priorityListing' filter is not supported for the specified sort option. Refer to the API call documentation.
12515API_BROWSEREQUESTThe '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.

CodeDomainCategoryMeaning
12002API_BROWSEREQUESTThe {filterName} value is invalid. For the valid values, refer to the API call documentation.
12003API_BROWSEREQUESTA seller 'username' provided in the request filters is invalid.
12008API_BROWSEREQUESTThe 'sort' value is invalid. For the valid values, refer to the API call documentation.
12009API_BROWSEREQUESTThe 'category_ids' query parameter is invalid.
12010API_BROWSEREQUESTThere are four filters required for local pickup. 'pickupPostalCode','pickupCountry','pickupRadiusUnit','pickupRadius'. One or more is missing or invalid.
12011API_BROWSEREQUEST'deliveryCountry' is a mandatory filter to provide a delivery location. 'deliveryPostalCode' is optional.
12012API_BROWSEREQUESTA valid 'price' filter and a valid 'priceCurrency' filter is necessary to filter based on price.
12014API_BROWSEBUSINESSThe 'sellerAccountTypes' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}
12015API_BROWSEREQUESTThe postal code filter value is invalid for the specified country and this filter was ignored.
12016API_BROWSEREQUESTThe 'fieldgroups' value {fieldgroups} is invalid. For the valid values, refer to the API call reference documentation
12017API_BROWSEREQUESTThe 'aspect_filter' query parameter must include a categoryId. For information, see the API call reference documentation.
12018API_BROWSEREQUESTThe {aspectFilter} aspect_filter value is invalid. For information, see the API call reference documentation.
12024API_BROWSEREQUESTThe 'charity_ids' value {charity_id} is invalid. For more information see the API call reference documentation.
12031API_BROWSEREQUESTThe following filter(s) is/are not supported by this operation: {unsupportedFilters}. For more information see the API call reference documentation.
12511API_BROWSEREQUESTEither '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 Image

This call searches for items using an image ID.

Input

The Base64 ID of an image, which in this case is an image of a drill, in the request payload. There are no URI parameters required.

POSThttps://api.ebay.com/buy/browse/v1/item_summary/search_by_image?&limit=3&sort=-price

Output

This call returns items that are similar to the image ID submitted sort by price from smallest to largest.