--- title: Browse API description: "The **Browse API** lets shoppers search eBay listings by keyword, category, GTIN, product, charity, compatibility criteria, or image, and refine results with filters such as aspects, compatibility, field values, and UI parameters through the **item\\_summary** resource. The **item** resource lets applications retrieve detailed information for a specific item or all items in an item group, and check whether a product is compatible with a specified item, such as whether a specific vehicle is compatible with a specific part. The **item** resource also supports legacy item identifiers alongside RESTful item IDs, which use different formats. This helps developers work with stored or historical legacy item IDs when using the **Browse API**. All methods in the **Browse API** require an Application access token, which is obtained using the [client credentials grant flow](/develop/guides-v2/authorization#the-client-credentials-grant-flow)." api_version: 1.0 api_name: browse_api api_type: REST api_group: buy/browse_api source_url: html: https://developer.ebay.com/develop/api/buy/browse_api md: https://developer.ebay.com/develop/api/buy/browse_api.md --- # Browse API API The **Browse API** lets shoppers search eBay listings by keyword, category, GTIN, product, charity, compatibility criteria, or image, and refine results with filters such as aspects, compatibility, field values, and UI parameters through the **item\_summary** resource. The **item** resource lets applications retrieve detailed information for a specific item or all items in an item group, and check whether a product is compatible with a specified item, such as whether a specific vehicle is compatible with a specific part. The **item** resource also supports legacy item identifiers alongside RESTful item IDs, which use different formats. This helps developers work with stored or historical legacy item IDs when using the **Browse API**. All methods in the **Browse API** require an Application access token, which is obtained using the [client credentials grant flow](/develop/guides-v2/authorization#the-client-credentials-grant-flow). ## API Methods The following API methods are available: ### search #### GET /item_summary/search **Description:** 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` remains 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, refer to 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 additional information and examples of these capabilities, refer to [Browse API](/api-docs/buy/static/api-browse.html) 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 are returned. By default, results are sorted by _Best Match_. For more information about Best Match, refer to [Best Match](). **Restrictions** This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, refer to [Buy APIs Requirements](/api-docs/buy/static/buy-requirements.html). **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. **Parameters:** - **aspect_filter** (string) - 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. **Note:** The category ID must be specified _twice_: * Once as a URI parameter in the `category_ids` field * Once as part of the `aspect_filter` field These two values **must** be the same. For example, to return items for a woman's red shirt, issue the following request: /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` as illustrated here: /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 illustrates 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} - **auto_correct** (string) - A query parameter that enables auto correction. A sample is shown below: /buy/browse/v1/item\_summary/search?auto\_correct=KEYWORD **Note:** Auto correction is currently supported in the following marketplaces: * United States * Austria * Australia * Canada * Switzerland * Germany * Spain * France * United Kingdom * Ireland * Italy **Valid Values:** `KEYWORD` - **category_ids** (string) - The category ID is used to limit the results that are returned. This field may pass in one category ID or a comma separated list of IDs as illustrated in the following examples: /buy/browse/v1/item\_summary/search?category\_ids=29792 /buy/browse/v1/item\_summary/search?category\_ids=267,29792 **Note:** Currently, you can pass in only one category ID per request. To refine the set of information that is returned, `category_ids` may be combined with **EITHER**: * `epid` and/or `gtin` values * `q` keywords For example, when looking of a toy phone, simply searching for "phone" will return mobile phones because that is the "Best Match" for the search. To further refine the request to include toy phones, include the **Toys & Hobbies** category ID as illustrated here: /buy/browse/v1/item\_summary/search?q=phone&category\_ids=220 Because the list of eBay category IDs is not published and category IDs are not the same across all eBay marketplaces, category IDs may be determined by: * Visiting the [Category Changes page]() * Using the Taxonomy API. Refer to [Get Categories for Buy APIs](/api-docs/buy/buy-categories.html) for complete information. * Issuing the following call to retrieve the `dominantCategoryId` for an item: /buy/browse/v1/item\_summary/search?q= _keyword_&fieldgroups=ASPECT\_REFINEMENTS **Note:** If a top-level (L1) category is specified, you **must** also include a `q` query parameter. - **charity_ids** (string) - The charity ID filters results to return only those items associated with the specified charity. **Note:** `charity_ids` is only supported by the US and UK marketplaces. Charity ID is a charity's unique identification number: * In the US, this is the **Employer Identification Number (EIN)**. * In the UK, this is the Charity Registration Number (CRN), commonly called **Charity Number**. `charity_ids` may be retrieved/determined as follows: * Search for a supported charity using the Charity API's [getCharityOrgs](/api-docs/commerce/charity/resources/charity_org/methods/getCharityOrgs) method. **Important!** The value to be passed in as `charity_ids` is that returned in the `registrationId` field. * Search for a supported charity by visiting [Charity Search](). Click on the charity's name to display its information. The EIN number is included in the charity's information block at the top of the page. For example, the charity ID for [American Red Cross](), is `530196605`. Up to 20 comma-separated `charity_ids` may be specified in each query. Additionally, `charity_ids` may be combined with `category_ids` and/or `q` keyword values to further filter returned results. A sample query using `charity_ids` is: /buy/browse/v1/item\_summary/search?charity\_ids=13-1788491,300108469 - **compatibility_filter** (string) - 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](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.itemsummary.compatibilitymatch) value that indicates how well the item matches the attributes. **Tip:** Refer to the **Samples** for a detailed example. **Best Practice:** Submit all of the [product attributes](/api-docs/buy/static/api-browse.html#product-attributes) for the specific product. To find the attributes and values for a specific marketplace, use the [getCompatibilityProperties](/api-docs/commerce/taxonomy/resources/category_tree/methods/getCompatibilityProperties) method in the [Taxonomy API](/api-docs/commerce/taxonomy/resources/methods). For more information, refer to [Check compatibility](/api-docs/buy/static/api-browse.html#Check) in the Buying Integration Guide. **Note:** Testing in Sandbox is only supported using mock data. Refer to [Testing search in the Sandbox](/api-docs/buy/static/api-browse.html#sbox-test) for details. **Required:** * `q` (keyword) * One parts-compatibility-supported category ID (such as `33559` Brakes) * At least one [vehicle attribute](/api-docs/buy/static/api-browse.html#product-attributes) name/value pair - **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. Use the [product\_summary/search](/api-docs/commerce/catalog/resources/product_summary/methods/search) method in the [Catalog](/api-docs/commerce/catalog/overview.html) API to search for the ePID of the product. For example: /buy/browse/v1/item\_summary/search?epid=15032 **Note:** When constructing a query, `epid` may be combined with a `gtin` value. However, _do not_ specify keywords using the `q` parameter — keywords cannot be used in conjunction with an `epid`. - **fieldgroups** (string) - A comma-separated list of values that controls 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 field group adds the [aspectDistributions](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.refinement.aspectdistributions) container to the response. **Note:** Information returned by `ASPECT_REFINEMENTS` is category specific. * `BUYING_OPTION_REFINEMENTS` This field group adds the [buyingOptionDistributions](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.refinement.buyingoptiondistributions) container to the response. * `CATEGORY_REFINEMENTS` This field group adds the [categoryDistributions](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.refinement.categorydistributions) container to the response. * `CONDITION_REFINEMENTS` This field group adds the [conditionDistributions](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.refinement.conditiondistributions) containers, such as `NEW`, `USED`, etc., to the response. 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 field group adds the following fields to the response: * [shortDescription](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.itemsummary.shortdescription) * [itemLocation.city](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.itemlocationimpl.city) * `MATCHING_ITEMS` (**default value**) This field group is intended to be used with one or more of the refinement values listed above. This is used to return the specified refinements and all matching items. * `FULL` This field group returns all refinement containers and all matching items. **Default:** `MATCHING_ITEMS` - **filter** (string) - An array of field filters that can be used to limit/customize the result set. Refer to [Buy API Field Filters](/api-docs/buy/static/ref-buy-browse-filters.html) for additional information and examples of all supported filters. For example, to filter shirts based on a specific range of prices, include the filter illustrated here: /buy/browse/v1/item\_summary/search?q=shirt&filter=price:\[10..50\] Filters may also be combined within a single request as illustrated in the sample below which further refines results to return only those shirts available from specific sellers: /buy/browse/v1/item\_summary/search?q=shirt&filter=price:\[10..50\],sellers:{rpseller|bigSal} - **gtin** (string) - This field lets you search for a product by specifying a Global Trade Item Number (GTIN) of the product. Supported GTIN types are UPC, EAN, and ISBN. For example: /buy/browse/v1/item\_summary/search?gtin=099482432621 **Note:** When constructing a query, `gtin` value may be combined with an `epid` value, but neither an `epid` or `gtin` value should be combined with a keywords search through the `q` parameter. - **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 `offset` values. **Note:** This method can return a maximum of 10,000 items in one results set. **Min:** 1 **Max:** 200 **Default:** 50 - **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 `offset` values. **Note:** This method can return a maximum of 10,000 items in one results set. **Min**: 0 **Max:** 9,999 **Default:** 0 - **q** (string) - A string consisting of one or more keywords used to search for items on eBay. **Note:** The `*` wildcard character is **not** allowed in this field. When providing two or more keywords in a single query, the string is processed as follows: * When successive keywords are separated by a space, the list of keywords is processed as an `AND` request. For example, to retrieve items that include **both** of the keywords **iphone** AND **ipad**, submit the following query: /buy/browse/v1/item\_summary/search?q=iphone ipad * When successive keywords are comma-separated and surrounded by a single pair of parentheses, OR if the keywords are each URL-encoded, the list of keywords is processed as an `OR` request. For example, to retrieve items that include **iphone** OR **ipad**, submit one of the following queries: /buy/browse/v1/item\_summary/search?q=(iphone, ipad) /buy/browse/v1/item\_summary/search?q=%28iphone%2c%20ipad%29 **Note:** When specifying keywords using the `q` parameter: * _Do not include_ an `epid` or `gtin` parameter value as neither can be used in conjunction with a keyword search. * Strings longer than 100-characters are truncated. **Maximum length:** 100 characters - **sort** (string) - Specifies the criteria on which returned items are to be sorted. Items can be sorted in ascending order based on: * Price (`sort=price`) Returned items are sorted based on their total cost (i.e., _price + shipping cost_). Items with the lowest combined price are shown first. When sorting by price, it is highly recommended that: * The `X-EBAY-C-ENDUSERCTX` request header is used, **and** * The `contextualLocation` parameter specifies the delivery country and postal code. These values must be _URL-encoded_. Refer to the following example: X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406 **Descending price order** To sort items from _highest price_ to _lowest price_ insert a minus sign (-) before `price` as the search criterion: sort=-price * Distance (`sort=distance`) Returned items are sorted based on their distance from the buyer's location. Items that are closest to the buyer are listed first. **Important!** When sorting by distance, all required [pickup filters](/api-docs/buy/static/ref-buy-browse-filters.html#pickupCountry) must be included in the request. * Date Items can be sorted by date based on: * Listing date (`sort=newlyListed`) Returned items are sorted based on their [itemOriginDate](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.itemsummary.itemorigindate). Newly listed items are shown first. * End date (`sort=endingSoonest`) Returned items are sorted based on the date/time on which their listing is scheduled to end. Items that are closest to their scheduled ending date/time are shown first. If no sort parameter is submitted, the result set is sorted by "Best Match". Refer to [Optimizing your listings for Best Match]() for additional information. - **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](/api-docs/buy/static/api-browse.html#Headers) in the [Buying Integration Guide](/api-docs/buy/static/buying-ig-landing.html). - **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 the marketplace ID value is invalid or missing, the default value of `EBAY_US` is used. See [MarketplaceIdEnum](/develop/api/buy/browse_api#buy-browse_api-item_summary-search.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` - **Accept-Language** (string) - This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example: * When targeting the French locale of the Belgium marketplace, it is required to pass in `fr-BE` to specify this. If this locale is not specified, the language will default to Dutch. * When targeting the French locale of the Canadian marketplace, it is required to pass in `fr-CA` to specify this. If this locale is not specified, the language will default to English. ### searchByImage #### POST /item_summary/search_by_image **Description:** 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 with other available filters. 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, refer to the **filter** parameter. * Filtering by item aspects using the **aspect\_filter** parameter. For details and examples of these capabilities, refer to [Browse API](/api-docs/buy/static/api-browse.html) in the Buying Integration Guide. **URL Encoding for Parameters** Query parameter values need to be URL encoded. For details, refer to [URL encoding query parameter values](/api-docs/static/rest-request-components.html#parameters). 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, refer to [Buy APIs Requirements](/api-docs/buy/static/buy-requirements.html). **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. **Parameters:** - **aspect_filter** (string) - 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. **Note:** The category ID must be specified _twice_: * Once as a URI parameter in the `category_ids` field * Once as part of the `aspect_filter` field These two values **must** be the same. For example, to return items for a woman's red shirt, issue the following request: /buy/browse/v1/item\_summary/search\_by\_image?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` as illustrated here: /buy/browse/v1/item\_summary/search\_by\_image?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 illustrates 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\_by\_image?limit=50&category\_ids=3034&filter=buyingOptions:{AUCTION|FIXED\_PRICE}&aspect\_filter=categoryId:3034,Brand:{Bed\\|Stü|Nike} - **category_ids** (string) - The category ID is used to limit the results that are returned. This field may pass in one category ID or a comma separated list of IDs as illustrated in the following examples: /buy/browse/v1/item\_summary/searchByImage?category\_ids=29792 /buy/browse/v1/item\_summary/searchByImage?category\_ids=267,29792 **Note:** Currently, you can pass in only one category ID per request. To refine the set of information that is returned, `category_ids` may be combined with other available filters. Because the list of eBay category IDs is not published and category IDs are not the same across all eBay marketplaces, category IDs may be determined by: * Visiting the [Category Changes page]() * Using the Taxonomy API. Refer to [Get Categories for Buy APIs](/api-docs/buy/buy-categories.html) for complete information. * Issuing the following call to retrieve the `dominantCategoryId` for an item: /buy/browse/v1/item\_summary/searchByImage?fieldgroups=ASPECT\_REFINEMENTS - **charity_ids** (string) - The charity ID filters results to return only those items associated with the specified charity. **Note:** `charity_ids` is only supported by the US and UK marketplaces. Charity ID is a charity's unique identification number: * In the US, this is the **Employer Identification Number (EIN)**. * In the UK, this is the Charity Registration Number (CRN), commonly called **Charity Number**. `charity_ids` may be retrieved/determined as follows: * Search for a supported charity using the Charity API's [getCharityOrgs]() method. **Important!** The value to be passed in as `charity_ids` is that returned in the `registrationId` field. * Search for a supported charity by visiting [Charity Search](). Click on the charity's name to display its information. The EIN number is included in the charity's information block at the top of the page. For example, the charity ID for [American Red Cross](), is `530196605`. Up to 20 comma-separated `charity_ids` may be specified in each query. Additionally, `charity_ids` may be combined with `category_ids` values to further filter returned results. A sample query using `charity_ids` is: /buy/browse/v1/item\_summary/search\_by\_image?charity\_ids=13-1788491,300108469 - **fieldgroups** (string) - A comma-separated list of values that controls 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 field group adds the [aspectDistributions](/develop/api/buy/browse_api#buy-browse_api-item_summary-searchbyimage.refinement.aspectdistributions) container to the response. **Note:** Information returned by `ASPECT_REFINEMENTS` is category specific. * `BUYING_OPTION_REFINEMENTS` This field group adds the [buyingOptionDistributions](/develop/api/buy/browse_api#buy-browse_api-item_summary-searchbyimage.refinement.buyingoptiondistributions) container to the response. * `CATEGORY_REFINEMENTS` This field group adds the [categoryDistributions](/develop/api/buy/browse_api#buy-browse_api-item_summary-searchbyimage.refinement.categorydistributions) container to the response. * `CONDITION_REFINEMENTS` This field group adds the [conditionDistributions](/develop/api/buy/browse_api#buy-browse_api-item_summary-searchbyimage.refinement.conditiondistributions) containers, such as `NEW`, `USED`, etc., to the response. 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 field group adds the following fields to the response: * [shortDescription](/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.shortDescription) * [itemLocation.city](/develop/api/buy/browse_api#buy-browse_api-item_summary-searchbyimage.itemlocationimpl.city) * `MATCHING_ITEMS` (**default value**) This field group is intended to be used with one or more of the refinement values listed above. This is used to return the specified refinements and all matching items. * `FULL` This field group returns all refinement containers and all matching items. **Default:** `MATCHING_ITEMS` - **filter** (string) - An array of field filters that can be used to limit/customize the result set. Refer to [Buy API Field Filters](/api-docs/buy/static/ref-buy-browse-filters.html) for the information about available filters. For example, to filter shirts based on a specific range of prices, include the filter illustrated here: /buy/browse/v1/item\_summary/search\_by\_image?filter=price:\[10..50\] Filters may also be combined within a single request as illustrated in the sample below which further refines results to return only those shirts available from specific sellers: /buy/browse/v1/item\_summary/search\_by\_image?filter=price:\[10..50\],sellers:{rpseller|bigSal} **Note:** Refer to [Buy API Field Filters](/api-docs/buy/static/ref-buy-browse-filters.html) for additional information and examples of all supported filters. - **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 `offset` values. **Note:** This method can return a maximum of 10,000 items in one results set. **Min:** 1 **Max:** 200 **Default:** 50 - **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 `offset` values. **Note:** This method can return a maximum of 10,000 items in one results set. **Min**: 0 **Max:** 9,999 **Default:** 0 - **sort** (string) - **Note:** This call currently returns results in a best-match order. This query parameter presently has no practical use. - **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](/api-docs/buy/static/api-browse.html#Headers) in the [Buying Integration Guide](/api-docs/buy/static/buying-ig-landing.html). - **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 the marketplace ID value is invalid or missing, the default value of `EBAY_US` is used. See [MarketplaceIdEnum](/develop/api/buy/browse_api#buy-browse_api-item_summary-searchbyimage.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` - **Content-Type** (string) *required* - This 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](/api-docs/static/rest-request-components.html#HTTP). - **Accept-Language** (string) - This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example: * When targeting the French locale of the Belgium marketplace, it is required to pass in `fr-BE` to specify this. If this locale is not specified, the language will default to Dutch. * When targeting the French locale of the Canadian marketplace, it is required to pass in `fr-CA` to specify this. If this locale is not specified, the language will default to English. ### getItem #### GET /item/{item_id} **Description:** This method retrieves the details of a specific item, such as description, price, category, all item aspects, condition, return policies, seller feedback and score, shipping options, shipping costs, estimated delivery, and other information the buyer needs to make a purchasing decision. The Buy APIs are designed to let you create an eBay shopping experience in your app or website. This means you will need to know when something, such as the availability, quantity, etc., has changed in any eBay item you are offering. This is easily achieved by setting the **fieldgroups** URI parameter to one of the following values: * `COMPACT` Reduces the response to only those fields necessary in order to determine if any item detail has changed. This field group **must** be used alone. * `PRODUCT` Adds fields to the default response that return information about the product/item. This field group may also be used in conjunction with `ADDITIONAL_SELLER_DETAILS`. * `ADDITIONAL_SELLER_DETAILS` Adds an additional field to the response that returns the seller's user ID. This field group may also be used in conjunction with `PRODUCT`. * `CHARITY_DETAILS` Adds additional fields to the response that return charity information associated with the item, if applicable. For additional information, refer to **fieldgroups**. **Restrictions** For a list of supported sites and other restrictions, refer to [Buy APIs Restrictions](/api-docs/buy/static/buy-requirements.html). **eBay Partner Network:** In order to be commissioned for your sales, you must use the URL returned in the `itemAffiliateWebUrl` field to forward your buyer to the ebay.com site. **Parameters:** - **fieldgroups** (string) - This parameter controls what is returned in the response. If this field is not set, the method returns all the details of the item. **Note:** Multiple **fieldgroups** can be set and applied simultaneously. However, **COMPACT** **must** be used alone. Otherwise, an error will occur. **Valid Values:** * **PRODUCT** This field group adds the [product](/develop/api/buy/browse_api#buy-browse_api-item-getitem.item.product) container to the response. * **COMPACT** This field group returns only the following fields which let you quickly check if the availability or price of the item has changed, if the item has been revised by the seller, or if an item's top-rated plus status has changed for items you have stored. * **itemId** * **bidCount** * **currentBidPrice** * **eligibleForInlineCheckout** * **estimatedAvailabilities** * **gtin** * **immediatePay** * **itemAffiliateWebURL** * **itemCreationDate** * **itemWebUrl** * **legacyItemId** * **minimumPriceToBid** * **price** * **priorityListing** * **reservePriceMet** * **sellerItemRevision** * **shippingOptions** * **taxes** * **topRatedBuyingExperience** * **uniqueBidderCount** For Example: To determine if a stored item's information is current, perform the following: 1. Pass in the item ID and set `fieldgroups` to `COMPACT`. item/v1|4\*\*\*\*\*\*\*\*\*\*8|0?fieldgroups=COMPACT 2. Do one of the following: * If **sellerItemRevision** is returned and a revision number for this item _has not_ been stored, record the number and pass in the item ID in the **getItem** method to retrieve the most recent information. * If the revision number is different from the value you have stored, update the value and pass in the item ID in the **getItem** method to retrieve the most recent information. * If `sellerItemRevision` is _not_ returned or has not changed, where needed, update the item information with the information returned in the response. * **ADDITIONAL\_SELLER\_DETAILS** This adds the [userId](/develop/api/buy/browse_api#buy-browse_api-item-getitem.sellerdetail.userid) field to the response. * **CHARITY\_DETAILS** This adds the [charityTerms](/develop/api/buy/browse_api#buy-browse_api-item-getitem.item.charityterms) container to the response, if applicable. - **item_id** (string) *required* - This path parameter specifies the unique RESTful identifier of the item being retrieved. **RESTful Item ID Format:** `v1`|`_#_`|`_#_` For a single SKU listing, pass in the item ID: v1|2\*\*\*\*\*\*\*\*\*\*2|0 For a multi-SKU listing, pass in the identifier of the variation: v1|1\*\*\*\*\*\*\*\*\*\*2|4\*\*\*\*\*\*\*\*\*\*2 For more information about item IDs for RESTful APIs, refer to [Item ID legacy API compatibility overview](/api-docs/buy/static/api-browse.html#Legacy) in the [Buying Integration Guide](/api-docs/buy/static/buying-ig-landing.html). - **X-EBAY-C-ENDUSERCTX** (string) - This header is can be used in following two situations: * To retrieve the **itemAffiliateWebUrl** field in the response, the ePN affiliate can pass in their affiliate credentials using this header. For more information, see [Header for affiliate information.](/api-docs/buy/static/api-browse.html#affiliate-header) * If the listing is using calculated or flat-rate shipping with shipping rate tables, the user can use this header to provide country and postal code in order for the **shippingOption** container, which includes shipping costs and delivery estimates, to be returned. For more information, see [Header for shipping information accuracy.](/api-docs/buy/static/api-browse.html#X-EBAY-C-ENDUSERCTX-context) - **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 the marketplace ID value is invalid or missing, the default value of `EBAY_US` is used. See [MarketplaceIdEnum](/develop/api/buy/browse_api#buy-browse_api-item-getitem.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` - **Accept-Language** (string) - This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example: * When targeting the French locale of the Belgium marketplace, it is required to pass in `fr-BE` to specify this. If this locale is not specified, the language will default to Dutch. * When targeting the French locale of the Canadian marketplace, it is required to pass in `fr-CA` to specify this. If this locale is not specified, the language will default to English. - **quantity_for_shipping_estimate** (string) - This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the [shippingOptions](/develop/api/buy/browse_api#buy-browse_api-item-getitem.item.shippingoptions) container of the response. This value must be a positive integer value and should not exceed the quantity available in the listing. This field is not recommended for auction listings, as they will always have a quantity of 1. ### getItemByLegacyId #### GET /item/get_item_by_legacy_id **Description:** This method is a bridge between the eBay legacy APIs and the eBay Buy APIs. There are differences between how legacy APIs and RESTful APIs return the identifier of an "item" and what the item ID represents. This method lets you use the legacy item ids retrieve the details of a specific item, such as description, price, and other information the buyer needs to make a purchasing decision. It also returns the RESTful **item\_id**, which you can use with all the Buy API methods. For additional information about how to use legacy ids with the Buy APIs, refer to [Item ID legacy API compatibility overview](/api-docs/buy/static/api-browse.html#Legacy) in the Buying Integration guide. This method returns the item details and requires you to pass in either the **item\_id** of a non-variation item or the **item\_id** values for both the parent and child of an item group. **Note:** An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. When an item group is created, one of the item variations, such as the red shirt size L, is chosen as the "parent". All other items in the group are the children, such as the blue shirt size L, red shirt size M, etc. The **fieldgroups** URI parameter lets you control what is returned in the response: * Setting **fieldgroups** to `PRODUCT` adds additional fields to the default response that return information about the product of the item. * Setting the **fieldgroups** to `ADDITIONAL_SELLER_DETAILS` adds an additional field to the response that returns the seller's user ID. * Setting the **fieldgroups** to `CHARITY_DETAILS` adds additional fields to the response that return charity information associated with the item, if applicable. These **fieldgroups** can be used independently or at the same time. For additional information, refer to . **Restrictions** For a list of supported sites and other restrictions, refer to [Buy APIs Requirements](/api-docs/buy/static/buy-requirements.html). **eBay Partner Network:** In order to be commissioned for your sales, you must use the URL returned in the `itemAffiliateWebUrl` field to forward your buyer to the ebay.com site. **Parameters:** - **fieldgroups** (string) - This field controls what is returned in the response. If this field is not set, the method returns all details about the item. Multiple `fieldgroups` can be set. **Valid Values:** * **PRODUCT** This field group adds the [product](/develop/api/buy/browse_api#buy-browse_api-item-getitembylegacyid.item.product) container to the response. * **ADDITIONAL\_SELLER\_DETAILS** This field group adds the [userId](/develop/api/buy/browse_api#buy-browse_api-item-getitembylegacyid.sellerdetail.userid) field to the response. * **CHARITY\_DETAILS** This field group adds the [charityTerms](/develop/api/buy/browse_api#buy-browse_api-item-getitembylegacyid.item.charityterms) container to the response, if applicable. - **legacy_item_id** (string) *required* - This query parameter is the unique identifier that specifies the item being retrieved. **Note:** When passing in the ID for a multi-variation listing, you must also use the `legacy_variation_id` field and pass in the ID of the specific item variation. If not, all variation within the multi-SKU listing will be retrieved. The following is an example of using the value of the **ItemID** field for a specific item to get the RESTful `itemId` value. ``` browse/v1/item/get_item_by_legacy_id?legacy_item_id=1**********9 ``` - **legacy_variation_id** (string) - This query parameter specifies the legacy item ID of a specific item in a multi-variation listing, such as that for the _red shirt size L_ item. **Important!** A `legacy_item_id` value must always be passed in when specifying a `legacy_variation_id` value. - **legacy_variation_sku** (string) - This query parameter specifies the legacy SKU of an item. SKUs are the unique identifiers of an item created by the seller. The following is an example of using the value of the `ItemID` and `SKU` fields to get the RESTful `itemId` value. ``` browse/v1/item/get_item_by_legacy_id?legacy_item_id=1**********9&legacy_variation_sku=V**********M ``` **Important!** A `legacy_item_id` value must always be passed in when specifying a `legacy_variation_sku` value. - **X-EBAY-C-ENDUSERCTX** (string) - This header is can be used in following two situations: * To retrieve the **itemAffiliateWebUrl** field in the response, the ePN affiliate can pass in their affiliate credentials using this header. For more information, see [Header for affiliate information.](/api-docs/buy/static/api-browse.html#affiliate-header) * If the listing is using calculated or flat-rate shipping with shipping rate tables, the user can use this header to provide country and postal code in order for the **shippingOption** container, which includes shipping costs and delivery estimates, to be returned. For more information, see [Header for shipping information accuracy.](/api-docs/buy/static/api-browse.html#X-EBAY-C-ENDUSERCTX-context) - **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 the marketplace ID value is invalid or missing, the default value of `EBAY_US` is used. See [MarketplaceIdEnum](/develop/api/buy/browse_api#buy-browse_api-item-getitembylegacyid.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` - **Accept-Language** (string) - This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example: * When targeting the French locale of the Belgium marketplace, it is required to pass in `fr-BE` to specify this. If this locale is not specified, the language will default to Dutch. * When targeting the French locale of the Canadian marketplace, it is required to pass in `fr-CA` to specify this. If this locale is not specified, the language will default to English. - **quantity_for_shipping_estimate** (string) - This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the [shippingOptions](/develop/api/buy/browse_api#buy-browse_api-item-getitembylegacyid.item.shippingoptions) container of the response. This value must be a positive integer value and should not exceed the quantity available in the listing. This field is not recommended for auction listings, as they will always have a quantity of 1. ### getItems #### GET /item **Description:** This method retrieves the details about specific items that buyers need to make a purchasing decision. **Note:** This is a [![Limited Release](/cms/img/docs/partners-api.svg "Limited Release")(Limited Release)]() available only to select Partners. For this method, only the following fields are returned: `bidCount`, `currentBidPrice`, `eligibleForInlineCheckout`, `enabledForGuestCheckout`, `estimatedAvailabilities`, `gtin`, `immediatePay`, `itemAffiliateWebUrl`, `itemCreationDate`, `itemEndDate`, `itemId`, `itemWebUrl`, `legacyItemId`, `minimumPriceToBid`, `price`, `priorityListing`, `reservePriceMet`, `sellerItemRevision`, `taxes`, `topRatedBuyingExperience`, and `uniqueBidderCount`. The array `shippingOptions`, which comprises multiple fields, is also returned if the **X-EBAY-C-ENDUSERCTX** header is supplied. **Restrictions** For a list of supported sites and other restrictions, refer to [Buy APIs Requirements](/api-docs/buy/static/buy-requirements.html). **eBay Partner Network:** In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. **Parameters:** - **item_ids** (string) - A comma separated list of the unique identifiers of the items to retrieve (maximum 20). **Note:** In any given request, either `item_ids` **or** `item_group_ids` can be retrieved. Attempting to retrieve both will result in an error. **RESTful Item ID Format:** `v1`|`_#_`|`_#_` For a single SKU listing, pass in the item ID: v1|2\*\*\*\*\*\*\*\*\*\*2|0 For a multi-SKU listing, pass in the identifier of the variation: v1|1\*\*\*\*\*\*\*\*\*\*2|4\*\*\*\*\*\*\*\*\*\*2 For more information about item IDs for RESTful APIs, refer to [Item ID legacy API compatibility overview](/api-docs/buy/static/api-browse.html#Legacy) in the [Buying Integration Guide](/api-docs/buy/static/buying-ig-landing.html). - **item_group_ids** (string) - A comma separated list of the unique identifiers of the item groups being retrieved (maximum 10). **Note:** In any given request, either `item_ids` **or** `item_group_ids` can be retrieved. Attempting to retrieve both will result in an error. **RESTful Group Item ID Format:** `############` For example: 3\*\*\*\*\*\*\*\*\*\*9 - **X-EBAY-C-ENDUSERCTX** (string) - This header is can be used in following two situations: * To retrieve the **itemAffiliateWebUrl** field in the response, the ePN affiliate can pass in their affiliate credentials using this header. For more information, see [Header for affiliate information.](/api-docs/buy/static/api-browse.html#affiliate-header) * If the listing is using calculated or flat-rate shipping with shipping rate tables, the user can use this header to provide country and postal code in order for the **shippingOption** container, which includes shipping costs and delivery estimates, to be returned. For more information, see [Header for shipping information accuracy.](/api-docs/buy/static/api-browse.html#X-EBAY-C-ENDUSERCTX-context) - **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 the marketplace ID value is invalid or missing, the default value of `EBAY_US` is used. See [MarketplaceIdEnum](/develop/api/buy/browse_api#buy-browse_api-item-getitembylegacyid.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` - **Accept-Language** (string) - This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example: * When targeting the French locale of the Belgium marketplace, it is required to pass in `fr-BE` to specify this. If this locale is not specified, the language will default to Dutch. * When targeting the French locale of the Canadian marketplace, it is required to pass in `fr-CA` to specify this. If this locale is not specified, the language will default to English. - **quantity_for_shipping_estimate** (string) - This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the [shippingOptions](/develop/api/buy/browse_api#buy-browse_api-item-getitembylegacyid.item.shippingoptions) container of the response. This value must be a positive integer value and should not exceed the quantity available in the listing. This field is not recommended for auction listings, as they will always have a quantity of 1. ### getItemsByItemGroup #### GET /item/get_items_by_item_group **Description:** This method retrieves details about individual items in an item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. You pass in the **item\_group\_id** as a URI parameter. This method returns two main containers: * **items** This container has an array of containers with the details about each item in the group. * **commonDescriptions** This container has an array of containers for a description and the `item_ids` for all items that have this exact description. Because items within an item group often have the same description, this decreases the size of the response. Setting the **fieldgroup** to `ADDITIONAL_SELLER_DETAILS` adds an additional field to the response that returns the seller's user ID. Setting the **fieldgroup** to `CHARITY_DETAILS` adds additional fields to the response that returns charity information associated with the item, if applicable. For more information, refer to **fieldgroups**. **Restrictions** For a list of supported sites and other restrictions, refer to [Buy APIs Restrictions](/api-docs/buy/static/buy-requirements.html). **eBay Partner Network:** In order to be commissioned for your sales, you must use the URL returned in the `itemAffiliateWebUrl` field to forward your buyer to the ebay.com site. **Parameters:** - **fieldgroups** (string) - This field controls what is returned in the response. If this field is not set, the method returns all details about the item. **Valid Values:** **ADDITIONAL\_SELLER\_DETAILS** - This field group adds the [userId](/develop/api/buy/browse_api#buy-browse_api-item-getitemsbyitemgroup.sellerdetail.userid) field to the response. **CHARITY\_DETAILS** - This field group adds the [charityTerms](/develop/api/buy/browse_api#buy-browse_api-item-getitemsbyitemgroup.item.charityterms) container to the response, if applicable. - **item_group_id** (string) *required* - This query parameter specifies the unique identifier of an item group for which information is to be returned. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. This ID is returned in the **itemGroupHref** field of the [search](/develop/api/buy/browse_api#buy-browse_api-item_summary-search) and [getItem](/develop/api/buy/browse_api#buy-browse_api-item-getitem) methods. **For Example:** https://api.ebay.com/buy/browse/v1/item/get\_items\_by\_item\_group?item\_group\_id=3\*\*\*\*\*\*\*\*\*\*6 - **X-EBAY-C-ENDUSERCTX** (string) - This header is can be used in following two situations: * To retrieve the **itemAffiliateWebUrl** field in the response, the ePN affiliate can pass in their affiliate credentials using this header. For more information, see [Header for affiliate information.](/api-docs/buy/static/api-browse.html#affiliate-header) * If the listing is using calculated or flat-rate shipping with shipping rate tables, the user can use this header to provide country and postal code in order for the **shippingOption** container, which includes shipping costs and delivery estimates, to be returned. For more information, see [Header for shipping information accuracy.](/api-docs/buy/static/api-browse.html#X-EBAY-C-ENDUSERCTX-context) - **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 the marketplace ID value is invalid or missing, the default value of `EBAY_US` is used. See [MarketplaceIdEnum](/develop/api/buy/browse_api#buy-browse_api-item-getitemsbyitemgroup.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` - **Accept-Language** (string) - This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example: * When targeting the French locale of the Belgium marketplace, it is required to pass in `fr-BE` to specify this. If this locale is not specified, the language will default to Dutch. * When targeting the French locale of the Canadian marketplace, it is required to pass in `fr-CA` to specify this. If this locale is not specified, the language will default to English. - **quantity_for_shipping_estimate** (string) - This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the [shippingOptions](/develop/api/buy/browse_api#buy-browse_api-item-getitemsbyitemgroup.item.shippingoptions) container of the response. This value must be a positive integer value and should not exceed the quantity available in the listing. This field is not recommended for auction listings, as they will always have a quantity of 1. ### checkCompatibility #### POST /item/{item_id}/check_compatibility **Description:** This method checks if a product is compatible with the specified item. You can use this method to check the compatibility of cars, trucks, and motorcycles with a specific part listed on eBay. For example, to check the compatibility of a part, you pass in the **item\_id** of the part as a URI parameter and specify all the attributes used to define a specific car within the **compatibilityProperties** container. If the call is successful, the response will be `COMPATIBLE`, `NOT_COMPATIBLE`, or `UNDETERMINED`. Refer to [compatibilityStatus](/develop/api/buy/browse_api#buy-browse_api-item-checkcompatibility.compatibilityresponse.compatibilitystatus) for details. **Note:** The only products supported are cars, trucks, and motorcycles. To find the attributes and values for a specific marketplace, you can use the compatibility methods in the [Taxonomy API](/api-docs/commerce/taxonomy/resources/methods). You can use this data to create menus to help buyers specify the product, such as their car. For more information and a list of required attributes for the US marketplace that describe motor vehicles, refer to [Check compatibility](/api-docs/buy/static/api-browse.html#Check) in the _Buying Integration Guide_. For an example, refer to the **Samples** section. **Note:** This method is supported in Sandbox but _only_ when passing in the specified `item_id` and compatibility name-value pairs listed in **Sample: Sandbox Sample**. **Restrictions** For a list of supported sites and other restrictions, refer to [Buy APIs Restrictions](/api-docs/buy/static/buy-requirements.html). **Parameters:** - **item_id** (string) *required* - This path parameter specifies the unique RESTful identifier of an item (such as the park you want to check). **RESTful Item ID Format:** `v1`|`_#_`|`_#_` For a single SKU listing, pass in the item ID: v1|2\*\*\*\*\*\*\*\*\*\*2|0 For a multi-SKU listing, pass in the identifier of the variation: v1|1\*\*\*\*\*\*\*\*\*\*2|4\*\*\*\*\*\*\*\*\*\*2 For more information about item IDs for RESTful APIs, refer to [Item ID legacy API compatibility overview](/api-docs/buy/static/api-browse.html#Legacy) in the [Buying Integration Guide](/api-docs/buy/static/buying-ig-landing.html). - **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 the marketplace ID value is invalid or missing, the default value of `EBAY_US` is used. See [MarketplaceIdEnum](/develop/api/buy/browse_api#buy-browse_api-item-getitem.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` - **Content-Type** (string) *required* - This 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](/api-docs/static/rest-request-components.html#HTTP) in the [Using eBay RESTful APIs](/api-docs/static/ebay-rest-landing.html) guide. - **Accept-Language** (string) - This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example: * When targeting the French locale of the Belgium marketplace, it is required to pass in `fr-BE` to specify this. If this locale is not specified, the language will default to Dutch. * When targeting the French locale of the Canadian marketplace, it is required to pass in `fr-CA` to specify this. If this locale is not specified, the language will default to English. ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 12001 - API_BROWSE **Description:** The call must have a valid 'q', 'category\_ids', 'epid' or 'gtin' query parameter. #### 12004 - API_BROWSE **Description:** The 'offset' value cannot be negative. #### 12005 - API_BROWSE **Description:** The 'offset' value must be an integer. #### 12006 - API_BROWSE **Description:** The 'limit' value should be between 1 and 200 (inclusive). #### 12007 - API_BROWSE **Description:** The 'limit' value must be an integer value. #### 12023 - API_BROWSE **Description:** 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 **Description:** The 'charity\_ids' field has exceeded the maximum limit of 20. #### 12026 - API_BROWSE **Description:** The 'charity\_ids' field is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}. #### 12027 - API_BROWSE **Description:** The 'auto\_correct' value is invalid. For the valid values, refer to the API call documentation. #### 12028 - API_BROWSE **Description:** The 'auto\_correct' is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}. #### 12029 - API_BROWSE **Description:** 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 **Description:** The number of categories in the request has exceeded the limit. Please reduce the number of categories to {allowedMaxCategories} or less. #### 12032 - API_BROWSE **Description:** The number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to {allowedMaxSellersInFilter} or less. #### 12033 - API_BROWSE **Description:** The 'qualifiedPrograms' filter for {filterValue} requires valid 'deliveryPostalCode' and 'deliveryCountry' filter values. #### 12034 - API_BROWSE **Description:** 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 **Description:** 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 **Description:** You must provide a category ID that supports fitment. #### 12505 - API_BROWSE **Description:** The following compatibility attributes in the request are not supported: {attributes}. #### 12506 - API_BROWSE **Description:** The category ID submitted does not support fitment. #### 12507 - API_BROWSE **Description:** To filter by 'guaranteedDeliveryInDays', you must include 'deliveryCountry'. #### 12508 - API_BROWSE **Description:** To filter by 'guaranteedDeliveryInDays', you must include 'deliveryPostalCode' for the 'deliveryCountry'. #### 12509 - API_BROWSE **Description:** 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 **Description:** The 'guaranteedDeliveryInDays' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}. #### 12512 - API_BROWSE **Description:** The 'qualifiedPrograms' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}. #### 12515 - API_BROWSE **Description:** The 'offset' value must be either zero or a multiple of the 'limit' value. #### 12516 - API_BROWSE **Description:** The 'q' value is invalid. It must be longer than one character when using the 'searchInDescription' filter. #### 12517 - API_BROWSE **Description:** Only one item location filter can be applied at a time. Refer to the API call documentation. #### 12518 - API_BROWSE **Description:** The 'itemLocationRegion' filter value is not supported for the marketplace {marketplaceId}. Valid values are: {validRegionValues}. #### 12520 - API_BROWSE **Description:** The 'conditionIds' filter value is invalid or not supported. For the supported values, refer to the API call documentation. #### 12521 - API_BROWSE **Description:** The request contains malformed URL encoding. Please check that all percent-encoded characters (%) are properly formatted. #### 12500 - API_BROWSE **Description:** This image search results in a response that is too large to return. Either change the image or add additional query parameters and/or filters. #### 12501 - API_BROWSE **Description:** The image data is empty, is not Base64 encoded, or is invalid. #### 11001 - API_BROWSE **Description:** The specified item ID was not found. #### 11002 - API_BROWSE **Description:** The specified item group was not found. #### 11004 - API_BROWSE **Description:** The item is not available for purchase. This can be for many reasons, such as when the listing is being updated by the seller. Wait a few minutes and try the call again. #### 11005 - API_BROWSE **Description:** The item group ID is invalid. Use {itemHref} to get the item details. #### 11008 - API_BROWSE **Description:** The item group is not available. This can be for many reasons, such as when the listing is being updated by the seller. Wait a few minutes and try the call again. #### 11011 - API_BROWSE **Description:** The marketplace value {marketplaceId} is not supported. The supported values are: {allowedMarketplaces} #### 11012 - API_BROWSE **Description:** The specified item IDs are invalid, or the format of the specified values are invalid. #### 11013 - API_BROWSE **Description:** The specified group IDs are invalid, or the format of the specified values are invalid. #### 11014 - API_BROWSE **Description:** An item\_ids and an item\_group\_ids list cannot be used at same time. Please use only one of these lists. #### 11015 - API_BROWSE **Description:** The maximum number of item ids has been exceeded. Please reduce the number of item ids to {maxAllowedItemIds} or less. #### 11016 - API_BROWSE **Description:** The maximum number of item group IDs has been exceeded. Please reduce the number of item group ids to {maxAllowedItemGroupIds} or less. #### 11018 - API_BROWSE **Description:** The specified fieldgroups are invalid. The COMPACT fieldgroup cannot be combined with another fieldgroup. #### 11019 - API_BROWSE **Description:** The quantity\_for\_shipping\_estimate value {quantityForShippingEstimate} is invalid. Please enter a positive value. #### 11501 - API_BROWSE **Description:** The 'fieldgroups' value(s) are invalid: {fieldgroups}. The supported fieldgroups are: {supportedFieldgroups}. #### 11003 - API_BROWSE **Description:** The specified legacy item ID was not found. #### 11006 - API_BROWSE **Description:** The legacy ID is invalid. Use {itemGroupHref} to get the item group details. #### 11009 - API_BROWSE **Description:** The legacy variation sku is invalid. #### 11010 - API_BROWSE **Description:** You cannot submit legacy\_variation\_sku and legacy\_variation\_id in the same request. For help, see the documentation. #### 11017 - API_BROWSE **Description:** An item\_ids or an item\_group\_ids list is required. Please use one of these lists. #### 11503 - API_BROWSE **Description:** The request is either empty or incomplete. For help, see the documentation for this call. #### 11504 - API_BROWSE **Description:** The following compatibilityProperties (attributes name/value pairs) are missing: {attributes}. #### 11505 - API_BROWSE **Description:** The item is not valid for compatibility validation. #### 11506 - API_BROWSE **Description:** The 'name' {compatibilityNames} appears more than once in the request. #### 11507 - API_BROWSE **Description:** The following name(s) in the request are not supported {attributes}. ### BUSINESS Errors #### 12013 - API_BROWSE **Description:** Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category. #### 12019 - API_BROWSE **Description:** Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} . #### 12020 - API_BROWSE **Description:** 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'. #### 12513 - API_BROWSE **Description:** The 'priorityListing' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}. #### 12514 - API_BROWSE **Description:** The 'priorityListing' filter is not supported for the specified sort option. Refer to the API call documentation. ### APPLICATION Errors #### 12000 - API_BROWSE **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. #### 11000 - API_BROWSE **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-07-09T00:26:44.795Z*