openapi: 3.0.0 info: title: eBay Account Advertising_eligibility Item_summary API description: The Account API gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information.

For details on the availability of the methods in this API, see Account API requirements and restrictions. contact: name: eBay Inc, license: name: eBay API License Agreement url: https://go.developer.ebay.com/api-license-agreement version: v1.9.2 servers: - url: https://api.ebay.com{basePath} description: Production variables: basePath: default: /sell/account/v1 tags: - name: Item_summary paths: /item_summary/search: get: tags: - Item_summary 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 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 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. operationId: search parameters: - name: aspect_filter in: query description: 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}

For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:AspectFilter required: false schema: type: string - name: auto_correct in: query description: 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 required: false schema: type: string - name: category_ids in: query description: 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 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. required: false schema: type: string - name: charity_ids in: query description: '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 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

' required: false schema: type: string - name: compatibility_filter in: query description: 'This field specifies the attributes used to define a specific product. The service searches for items matching the keyword, or matching the keyword and a product attribute value in the title of the item.

Note: The only products supported are cars, trucks, and motorcycles.
For example, if the keyword is brakes and compatibility-filter=Year:2018;Make:BMW, the items returned are items with brakes, 2018, or BMW in the title.

The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the CompatibilityMatchEnum value that indicates how well the item matches the attributes.

Tip: Refer to the Samples section for a detailed example.

Best Practice: Submit all of the product attributes for the specific product.

To find the attributes and values for a specific marketplace, use the getCompatibilityProperties method in the Taxonomy API.

For more information, refer to Check compatibility in the Buying Integration Guide.

Note: Testing in Sandbox is only supported using mock data. Refer to Testing search in the Sandbox for details.
Required:

q (keyword)
One parts-compatibility-supported category ID (such as 33559 Brakes)
At least one vehicle attribute name/value pair

For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityFilter' required: false schema: type: string - name: epid in: query description: 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 method in the Catalog 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. required: false schema: type: string - name: fieldgroups in: query description: 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 container to the response.

Note: Information returned by ASPECT_REFINEMENTS is category specific.
BUYING_OPTION_REFINEMENTS
This field group adds the buyingOptionDistributions container to the response.
CATEGORY_REFINEMENTS
This field group adds the categoryDistributions container to the response.
CONDITION_REFINEMENTS
This field group adds the 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
- itemLocation.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 required: false schema: type: string - name: filter in: query description: 'An array of field filters that can be used to limit/customize the result set.

Refer to Buy API Field Filters 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}

For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField' required: false schema: type: string - name: gtin in: query description: This field lets you search by the Global Trade Item Number of an item as defined by https://www.gtin.info.

For example:

/buy/browse/v1/item_summary/search?gtin=099482432621

Note: You can search only by UPC (Universal Product Code). To search using another GTIN format, you must search by keyword.Note: When constructing a query, gtin may be combined with an epid value. However, do not specify keywords using the q parameter — keywords cannot be used in conjunction with gtin. required: false schema: type: string - name: limit in: query description: 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 required: false schema: type: string - name: offset in: query description: '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' required: false schema: type: string - name: q in: query description: 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 conjuction with a keyword search. required: false schema: type: string - name: sort in: query description: '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 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 listing date.
  
  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. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:SortField' required: false schema: type: string - name: X-EBAY-C-ENDUSERCTX in: header description: 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 in the Buying Integration Guide. required: false schema: type: string - name: X-EBAY-C-MARKETPLACE-ID in: header description: This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US.

Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.
See MarketplaceIdEnum for supported values. required: false schema: type: string - name: Accept-Language in: header description: 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.
required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SearchPagedCollection' x-response-codes: errors: '12002': domain: API_BROWSE category: REQUEST description: The {filterName} value is invalid. For the valid values, refer to the API call documentation. '12003': domain: API_BROWSE category: REQUEST description: A seller 'username' provided in the request filters is invalid. '12008': domain: API_BROWSE category: REQUEST description: The 'sort' value is invalid. For the valid values, refer to the API call documentation. '12009': domain: API_BROWSE category: REQUEST description: The 'category_ids' query parameter is invalid. '12010': domain: API_BROWSE category: REQUEST description: There are four filters required for local pickup. 'pickupPostalCode','pickupCountry','pickupRadiusUnit','pickupRadius'. One or more is missing or invalid. '12011': domain: API_BROWSE category: REQUEST description: '''deliveryCountry'' is a mandatory filter to provide a delivery location. ''deliveryPostalCode'' is optional.' '12012': domain: API_BROWSE category: REQUEST description: A valid 'price' filter and a valid 'priceCurrency' filter is necessary to filter based on price. '12014': domain: API_BROWSE category: BUSINESS description: 'The ''sellerAccountTypes'' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12015': domain: API_BROWSE category: REQUEST description: The postal code filter value is invalid for the specified country and this filter was ignored. '12016': domain: API_BROWSE category: REQUEST description: The 'fieldgroups' value {fieldgroups} is invalid. For the valid values, refer to the API call reference documentation '12017': domain: API_BROWSE category: REQUEST description: The 'aspect_filter' query parameter must include a categoryId. For information, see the API call reference documentation. '12018': domain: API_BROWSE category: REQUEST description: The {aspectFilter} aspect_filter value is invalid. For information, see the API call reference documentation. '12021': domain: API_BROWSE category: REQUEST description: The 'epid' value {epid} is invalid. For information, see the API call reference documentation. '12022': domain: API_BROWSE category: REQUEST description: The 'gtin' value {gtin} is invalid. For information, see the API call reference documentation. '12024': domain: API_BROWSE category: REQUEST description: The 'charity_ids' value {charity_id} is invalid. For more information see the API call reference documentation. '12502': domain: API_BROWSE category: REQUEST description: The {compatibilityFilter} compatibility_filter is invalid. For information, see the API call reference documentation. '12511': domain: API_BROWSE category: REQUEST description: Either 'deliveryCountry' or 'deliveryPostalCode' is invalid, hence 'guaranteedDeliveryInDays' filter was ignored. '400': description: Bad Request x-response-codes: errors: '12001': domain: API_BROWSE category: REQUEST description: The call must have a valid 'q', 'category_ids', 'epid' or 'gtin' query parameter. '12004': domain: API_BROWSE category: REQUEST description: The 'offset' value cannot be negative. '12005': domain: API_BROWSE category: REQUEST description: The 'offset' value must be an integer. '12006': domain: API_BROWSE category: REQUEST description: The 'limit' value should be between 1 and 200 (inclusive). '12007': domain: API_BROWSE category: REQUEST description: The 'limit' value must be an integer value. '12023': domain: API_BROWSE category: REQUEST 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': domain: API_BROWSE category: REQUEST description: The 'charity_ids' field has exceeded the maximum limit of 20. '12026': domain: API_BROWSE category: REQUEST description: 'The ''charity_ids'' field is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}.' '12027': domain: API_BROWSE category: REQUEST description: The 'auto_correct' value is invalid. For the valid values, refer to the API call documentation. '12028': domain: API_BROWSE category: REQUEST description: 'The ''auto_correct'' is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12029': domain: API_BROWSE category: REQUEST 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': domain: API_BROWSE category: REQUEST description: The number of categories in the request has exceeded the limit. Please reduce the number of categories to {allowedMaxCategories} or less. '12032': domain: API_BROWSE category: REQUEST description: The number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to 250 or fewer. '12033': domain: API_BROWSE category: REQUEST description: The 'qualifiedPrograms' filter for {filterValue} requires valid 'deliveryPostalCode' and 'deliveryCountry' filter values. '12034': domain: API_BROWSE category: REQUEST 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': domain: API_BROWSE category: REQUEST 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': domain: API_BROWSE category: REQUEST description: You must provide a category ID that supports fitment. '12505': domain: API_BROWSE category: REQUEST description: 'The following compatibility attributes in the request are not supported: {attributes}.' '12506': domain: API_BROWSE category: REQUEST description: The category ID submitted does not support fitment. '12507': domain: API_BROWSE category: REQUEST description: To filter by 'guaranteedDeliveryInDays', you must include 'deliveryCountry'. '12508': domain: API_BROWSE category: REQUEST description: To filter by 'guaranteedDeliveryInDays', you must include 'deliveryPostalCode' for the 'deliveryCountry'. '12509': domain: API_BROWSE category: REQUEST 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': domain: API_BROWSE category: REQUEST description: 'The ''guaranteedDeliveryInDays'' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12512': domain: API_BROWSE category: REQUEST description: 'The ''qualifiedPrograms'' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12515': domain: API_BROWSE category: REQUEST description: The 'offset' value must be either zero or a multiple of the 'limit' value. '12516': domain: API_BROWSE category: REQUEST description: The ‘q’ value is invalid. It must be longer than one character when using the ‘searchInDescription’ filter. '12517': domain: API_BROWSE category: REQUEST description: Only one item location filter can be applied at a time. Refer to the API call documentation. '12518': domain: API_BROWSE category: REQUEST description: 'The ''itemLocationRegion'' filter value is not supported for the marketplace {marketplaceId}. Valid values are: {validRegionValues}' '409': description: Conflict x-response-codes: errors: '12013': domain: API_BROWSE category: BUSINESS description: Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category. '12019': domain: API_BROWSE category: BUSINESS description: 'Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .' '12020': domain: API_BROWSE category: BUSINESS 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': domain: API_BROWSE category: BUSINESS description: 'The ''priorityListing'' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12514': domain: API_BROWSE category: BUSINESS description: The 'priorityListing' filter is not supported for the specified sort option. Refer to the API call documentation. '500': description: Internal Server Error x-response-codes: errors: '12000': domain: API_BROWSE category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope /item_summary/search_by_image: post: tags: - Item_summary description: Note: This is an experimental method that is available to select developers approved by business units. For information about how to obtain access to this API in production, refer to 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 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 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. 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 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. operationId: searchByImage parameters: - name: aspect_filter in: query description: 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}
```
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:AspectFilter required: false schema: type: string - name: category_ids in: query description: 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 for complete information.
- Issuing the following call to retrieve the dominantCategoryId for an item:
```
/buy/browse/v1/item_summary/searchByImage?q= keyword&fieldgroups=ASPECT_REFINEMENTS
```
required: false schema: type: string - name: charity_ids in: query description: '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 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
```
' required: false schema: type: string - name: fieldgroups in: query description: 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 container to the response.
  
  Note: Information returned by ASPECT_REFINEMENTS is category specific.
- BUYING_OPTION_REFINEMENTS
  This field group adds the buyingOptionDistributions container to the response.
- CATEGORY_REFINEMENTS
  This field group adds the categoryDistributions container to the response.
- CONDITION_REFINEMENTS
  This field group adds the 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
  - itemLocation.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 required: false schema: type: string - name: filter in: query description: 'An array of field filters that can be used to limit/customize the result set.

Refer to Buy API Field Filters 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?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}
```
Note: Refer to Buy API Field Filters for additional information and examples of all supported filters. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField' required: false schema: type: string - name: limit in: query description: 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 required: false schema: type: string - name: offset in: query description: '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' required: false schema: type: string - name: sort in: query description: Note: This call currently returns results in a best-match order. This query parameter presently has no practical use. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:SortField required: false schema: type: string - name: X-EBAY-C-ENDUSERCTX in: header description: 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 in the Buying Integration Guide. required: false schema: type: string - name: X-EBAY-C-MARKETPLACE-ID in: header description: This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US.

Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.
See MarketplaceIdEnum for supported values. required: false schema: type: string - name: Content-Type in: header description: 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. required: true schema: type: string - name: Accept-Language in: header description: 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.
required: false schema: type: string requestBody: description: The container for the image information fields. content: application/json: schema: description: The container for the image information fields. $ref: '#/components/schemas/SearchByImageRequest' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SearchPagedCollection' x-response-codes: errors: '12002': domain: API_BROWSE category: REQUEST description: The {filterName} value is invalid. For the valid values, refer to the API call documentation. '12003': domain: API_BROWSE category: REQUEST description: A seller 'username' provided in the request filters is invalid. '12008': domain: API_BROWSE category: REQUEST description: The 'sort' value is invalid. For the valid values, refer to the API call documentation. '12009': domain: API_BROWSE category: REQUEST description: The 'category_ids' query parameter is invalid. '12010': domain: API_BROWSE category: REQUEST description: There are four filters required for local pickup. 'pickupPostalCode','pickupCountry','pickupRadiusUnit','pickupRadius'. One or more is missing or invalid. '12011': domain: API_BROWSE category: REQUEST description: '''deliveryCountry'' is a mandatory filter to provide a delivery location. ''deliveryPostalCode'' is optional.' '12012': domain: API_BROWSE category: REQUEST description: A valid 'price' filter and a valid 'priceCurrency' filter is necessary to filter based on price. '12014': domain: API_BROWSE category: BUSINESS description: 'The ''sellerAccountTypes'' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12015': domain: API_BROWSE category: REQUEST description: The postal code filter value is invalid for the specified country and this filter was ignored. '12016': domain: API_BROWSE category: REQUEST description: The 'fieldgroups' value {fieldgroups} is invalid. For the valid values, refer to the API call reference documentation '12017': domain: API_BROWSE category: REQUEST description: The 'aspect_filter' query parameter must include a categoryId. For information, see the API call reference documentation. '12018': domain: API_BROWSE category: REQUEST description: The {aspectFilter} aspect_filter value is invalid. For information, see the API call reference documentation. '12024': domain: API_BROWSE category: REQUEST description: The 'charity_ids' value {charity_id} is invalid. For more information see the API call reference documentation. '12031': domain: API_BROWSE category: REQUEST description: 'The following filter(s) is/are not supported by this operation: {unsupportedFilters}. For more information see the API call reference documentation.' '12511': domain: API_BROWSE category: REQUEST description: Either 'deliveryCountry' or 'deliveryPostalCode' is invalid, hence 'guaranteedDeliveryInDays' filter was ignored. '400': description: Bad Request x-response-codes: errors: '12004': domain: API_BROWSE category: REQUEST description: The 'offset' value cannot be negative. '12005': domain: API_BROWSE category: REQUEST description: The 'offset' value must be an integer. '12006': domain: API_BROWSE category: REQUEST description: The 'limit' value should be between 1 and 200 (inclusive). '12007': domain: API_BROWSE category: REQUEST description: The 'limit' value must be an integer value. '12025': domain: API_BROWSE category: REQUEST description: The 'charity_ids' field has exceeded the maximum limit of 20. '12026': domain: API_BROWSE category: REQUEST description: 'The ''charity_ids'' field is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}.' '12029': domain: API_BROWSE category: REQUEST 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': domain: API_BROWSE category: REQUEST description: The number of categories in the request has exceeded the limit. Please reduce the number of categories to {allowedMaxCategories} or less. '12032': domain: API_BROWSE category: REQUEST description: The number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to 250 or fewer. '12033': domain: API_BROWSE category: REQUEST description: The 'qualifiedPrograms' filter for {filterValue} requires valid 'deliveryPostalCode' and 'deliveryCountry' filter values. '12034': domain: API_BROWSE category: REQUEST description: The 'buyingOptions' filter value {filterValue} is not supported for the sort by {sortOption}. For the supported values, refer to the API call documentation. '12500': domain: API_BROWSE category: REQUEST 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': domain: API_BROWSE category: REQUEST description: The image data is empty, is not Base64 encoded, or is invalid. '12507': domain: API_BROWSE category: REQUEST description: To filter by 'guaranteedDeliveryInDays', you must include 'deliveryCountry'. '12508': domain: API_BROWSE category: REQUEST description: To filter by 'guaranteedDeliveryInDays', you must include 'deliveryPostalCode' for the 'deliveryCountry'. '12509': domain: API_BROWSE category: REQUEST 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': domain: API_BROWSE category: REQUEST description: 'The ''guaranteedDeliveryInDays'' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12512': domain: API_BROWSE category: REQUEST description: 'The ''qualifiedPrograms'' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12515': domain: API_BROWSE category: REQUEST description: The 'offset' value must be either zero or a multiple of the 'limit' value. '409': description: Conflict x-response-codes: errors: '12013': domain: API_BROWSE category: BUSINESS description: Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category. '12019': domain: API_BROWSE category: BUSINESS description: 'Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .' '12020': domain: API_BROWSE category: BUSINESS 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': domain: API_BROWSE category: BUSINESS description: 'The ''priorityListing'' filter for {filterValue} is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}' '12514': domain: API_BROWSE category: BUSINESS description: The 'priorityListing' filter is not supported for the specified sort option. Refer to the API call documentation. '500': description: Internal Server Error x-response-codes: errors: '12000': domain: API_BROWSE category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope components: schemas: AutoCorrections: type: object properties: q: type: string description: The automatically spell-corrected keyword from the request. ItemLocationImpl: type: object properties: addressLine1: type: string description: The first line of the street address. addressLine2: type: string description: The second line of the street address. This field may contain such values as an apartment or suite number. city: type: string description: The city in which the item is located.

Restriction: This field is populated in the search method response only when fieldgroups = EXTENDED. country: type: string description: The two-letter ISO 3166 standard code that indicates the country in which the item is located. For implementation help, refer to eBay API documentation county: type: string description: The county in which the item is located. postalCode: type: string description: The postal code (or zip code in US) where the item is located. Sellers set a postal code 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. stateOrProvince: type: string description: The state or province in which the item is located. description: The type that defines the fields for the location of an item, such as information typically used for an address, including postal code, county, state/province, street address, city, and country (2-digit ISO code). Refinement: type: object properties: aspectDistributions: type: array description: An array of containers for the all the aspect refinements. items: $ref: '#/components/schemas/AspectDistribution' buyingOptionDistributions: type: array description: An array of containers for the all the buying option refinements. items: $ref: '#/components/schemas/BuyingOptionDistribution' categoryDistributions: type: array description: An array of containers for the all the category refinements. items: $ref: '#/components/schemas/CategoryDistribution' conditionDistributions: type: array description: An array of containers for the all the condition refinements. items: $ref: '#/components/schemas/ConditionDistribution' dominantCategoryId: type: string description: 'The identifier of the category that most of the items are part of. ' description: This type defines the fields for the various refinements of an item. You can use the information in this container to create histograms, which help shoppers choose exactly what they want. ConditionDistribution: type: object properties: condition: type: string description: The text describing the condition of the item, such as New or Used. For a list of condition names, refer to Item Condition IDs and Names. conditionId: type: string description: The identifier of the condition. For example, 1000 is the identifier for NEW. matchCount: type: integer description: The number of items having the condition. format: int32 refinementHref: type: string description: The HATEOAS reference of this condition. description: The container that defines the fields for the conditions refinements. This container is returned when fieldgroups is set to CONDITION_REFINEMENTS or FULL in the request. TargetLocation: type: object properties: unitOfMeasure: type: string description: 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. value: type: string description: This value indicates the distance (measured in the measurement unit in the unitOfMeasure field) between the item location and the buyer's location. description: 'The type that defines the fields for the distance between the item location and the buyer''s location. ' MarketingPrice: type: object properties: discountAmount: description: This container returns the monetary amount of the seller discount. $ref: '#/components/schemas/ConvertedAmount' discountPercentage: type: string description: This field expresses the percentage of the seller discount based on the value in the originalPrice container. originalPrice: description: This container returns the monetary amount of the item without the discount. $ref: '#/components/schemas/ConvertedAmount' priceTreatment: type: string description: 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. For implementation help, refer to eBay API documentation description: The type that defines the fields that describe a seller discount. AspectDistribution: type: object properties: aspectValueDistributions: type: array description: An array of containers for the various values of the aspect and the match count, and a HATEOAS reference (refinementHref) for this aspect. items: $ref: '#/components/schemas/AspectValueDistribution' localizedAspectName: type: string description: The name of an aspect, such as Brand, Color, etc. description: The type that define the fields for the aspect information. Aspects are the variations of an item, such as color, size, etc. Image: type: object properties: height: type: integer description: Reserved for future use. format: int32 imageUrl: type: string description: The URL of the image. width: type: integer description: Reserved for future use. format: int32 description: Type that defines the details of an image, such as size and image URL. Currently, only imageUrl is populated. The height and width are reserved for future use. CategoryDistribution: type: object properties: categoryId: type: string description: The unique identifier of the category. categoryName: type: string description: The name of the category, such as Baby & Toddler Clothing. matchCount: type: integer description: The number of items in this category. format: int32 refinementHref: type: string description: The HATEOAS reference of this category. description: The container that defines the fields for the category refinements. This container is returned when fieldgroups is set to CATEGORY_REFINEMENTS or FULL in the request. ItemSummary: type: object properties: additionalImages: type: array description: 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. items: $ref: '#/components/schemas/Image' adultOnly: type: boolean description: This indicates if the item is for adults only. For more information about adult-only items on eBay, refer to the Adult items policy. availableCoupons: type: boolean description: This boolean attribute indicates if coupons are available for the item. bidCount: type: integer description: 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. format: int32 buyingOptions: type: array description: 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 are willing to pay for the item. The seller can accept, reject, or send a counter offer. For additional information about Best Offer, refer to Adding Best Offer to your listing and sending offers to buyers.
- CLASSIFIED_AD
  Indicates that the final sales transaction is to be completed outside of the eBay environment.
items: type: string categories: type: array description: This array returns the name and ID of each category associated with the item, including top level, branch, and leaf categories. items: $ref: '#/components/schemas/Category' compatibilityMatch: type: string description: This indicates how well an item matches the compatibility_filter product attributes.

Valid Values:
- EXACT
- POSSIBLE
For implementation help, refer to eBay API documentation compatibilityProperties: type: array description: 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. items: $ref: '#/components/schemas/CompatibilityProperty' condition: type: string description: The text describing the condition of the item, such as New or Used. For a list of condition names, refer to Item Condition IDs and Names. conditionId: type: string description: The identifier of the condition of the item. For example, 1000 is the identifier for NEW. For a list of condition names and IDs, refer to Item Condition IDs and Names. currentBidPrice: description: 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. $ref: '#/components/schemas/ConvertedAmount' distanceFromPickupLocation: description: 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. $ref: '#/components/schemas/TargetLocation' energyEfficiencyClass: type: string description: 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 returned only if the seller specifies the energy efficiency rating through item specifics at listing time. Rating values include A+++, A++, A+, A, B, C, D, E, F, and G. epid: type: string description: An ePID is the eBay product identifier of a product from the eBay product catalog. This indicates the product in which the item belongs. image: description: The URL to the primary image of the item. $ref: '#/components/schemas/Image' itemAffiliateWebUrl: type: string description: 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 returned only if:The marketplace through which the item is being viewed is part of the eBay Partner Network. Currently Singapore (EBAY_SG) is 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. itemCreationDate: type: string description: 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. itemEndDate: type: string description: 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. itemGroupHref: type: string description: 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. itemGroupType: type: string description: 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. itemHref: type: string description: The URI for the Browse API getItem method, which can be used to retrieve more details about items in the search results. itemId: type: string description: The unique RESTful identifier of the item. itemLocation: description: 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). $ref: '#/components/schemas/ItemLocationImpl' itemWebUrl: type: string description: 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. leafCategoryIds: type: array description: 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. items: type: string legacyItemId: type: string description: 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. listingMarketplaceId: type: string description: The ID of the eBay marketplace on which the seller listed the item. For implementation help, refer to eBay API documentation marketingPrice: description: 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. $ref: '#/components/schemas/MarketingPrice' pickupOptions: type: array description: This container returns the local pickup options available to the buyer. This container is returned only if the user is searching for local pickup items and set the local pickup filters in the method request. items: $ref: '#/components/schemas/PickupOptionSummary' price: description: 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 view 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 Your VAT Obligations in the UK & EU. $ref: '#/components/schemas/ConvertedAmount' priceDisplayCondition: type: string description: 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. For implementation help, refer to eBay API documentation priorityListing: type: boolean description: 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. qualifiedPrograms: type: array description: '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 the 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.' items: type: string seller: description: This container returns basic information about the seller of the item, such as name, feedback score, etc. $ref: '#/components/schemas/Seller' shippingOptions: type: array description: This container returns the shipping options available to ship the item. items: $ref: '#/components/schemas/ShippingOptionSummary' shortDescription: type: string description: 'This text string is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.) Sometimes the title does not provide 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.' thumbnailImages: type: array description: An array of thumbnail images for the item. items: $ref: '#/components/schemas/Image' title: type: string description: The seller-created title of the item. Maximum Length: 80 characters topRatedBuyingExperience: type: boolean description: '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. For more information, refer to Look for Top Rated Plus Items and Seller performance overview.' tyreLabelImageUrl: type: string description: The URL to the image that shows the information on the tyre label. unitPrice: description: '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"' $ref: '#/components/schemas/ConvertedAmount' unitPricingMeasure: type: string description: '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"' watchCount: type: integer description: 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 indicating that you want access to Watch Count data in the Browse API. format: int32 description: The type that defines the fields for the details of a specific item. SearchPagedCollection: type: object properties: autoCorrections: description: The auto-corrected inputs. $ref: '#/components/schemas/AutoCorrections' href: type: string description: 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. itemSummaries: type: array description: An array of the items on this page. The items are sorted according to the sorting method specified in the request. items: $ref: '#/components/schemas/ItemSummary' limit: type: integer description: 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. format: int32 next: type: string description: 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 offset: type: integer description: 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. format: int32 prev: type: string description: 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 refinement: description: The container for all the search refinements. $ref: '#/components/schemas/Refinement' total: type: integer description: 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. format: int32 warnings: type: array description: The container with all the warnings for the request. items: $ref: '#/components/schemas/Error' description: The type that defines the fields for a paginated result set. The response consists of 0 or more sequenced pages where each page has 0 or more items. ShippingOptionSummary: type: object properties: guaranteedDelivery: type: boolean description: Although this field is still returned, it can be ignored since eBay Guaranteed Delivery is no longer a supported feature on any marketplace. This field may get removed from the schema in the future. maxEstimatedDeliveryDate: type: string description: '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.' minEstimatedDeliveryDate: type: string description: 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. shippingCost: description: 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 Your VAT Obligations in the UK & EU. $ref: '#/components/schemas/ConvertedAmount' shippingCostType: type: string description: 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). description: The type that defines the fields for the shipping information. ConvertedAmount: type: object properties: convertedFromCurrency: type: string description: 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. For implementation help, refer to eBay API documentation convertedFromValue: type: string description: 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. currency: type: string description: 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. For implementation help, refer to eBay API documentation value: type: string description: 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. description: This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable. Error: type: object properties: category: type: string description: 'This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.' domain: type: string description: The name of the primary system where the error occurred. This is relevant for application errors. errorId: type: integer description: 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. format: int32 inputRefIds: type: array description: An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any. items: type: string longMessage: type: string description: A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem. message: type: string description: A description of the condition that caused the error or warning. outputRefIds: type: array description: An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any. items: type: string parameters: type: array description: 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. items: $ref: '#/components/schemas/ErrorParameter' subdomain: type: string description: The name of the subdomain in which the error or warning occurred. description: The type that defines the fields that can be returned in an error. PickupOptionSummary: type: object properties: pickupLocationType: type: string description: This container returns the local pickup options available to the buyer. Possible values are ARRANGED_LOCATION and STORE. description: The type that defines the fields for the local pickup options that are available for the item. It is used by the pickupOptions container. Category: type: object properties: categoryId: type: string description: The unique identifier of the category. categoryName: type: string description: The name of the category. description: This type is used by the categories container in the response of the search method, and contains the name and ID of the item category. Seller: type: object properties: feedbackPercentage: type: string description: The percentage of the total positive feedback. feedbackScore: type: integer description: The feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller. format: int32 sellerAccountType: type: string description: 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 username: type: string description: The user name created by the seller for use on eBay. description: The type that defines the fields for basic information about the seller of the item returned by the item_summary resource. CompatibilityProperty: type: object properties: localizedName: type: string description: The name of the product attribute that as been translated to the language of the site. name: type: string description: The name of the product attribute, such as Make, Model, Year, etc. value: type: string description: The value for the name attribute, such as BMW, R1200GS, 2011, etc. description: This container returns the product attribute name/value pairs that are compatible with the keyword. These attributes are submitted in the compatibility_filter request field. BuyingOptionDistribution: type: object properties: buyingOption: type: string description: 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. matchCount: type: integer description: The number of items having this buying option. format: int32 refinementHref: type: string description: The HATEOAS reference for this buying option. description: The container that defines the fields for the buying options refinements. This container is returned when fieldgroups is set to BUYING_OPTION_REFINEMENTS or FULL in the request. ErrorParameter: type: object properties: name: type: string description: This is the name of input field that caused an issue with the call request. value: type: string description: This is the actual value that was passed in for the element specified in the name field. description: An array of name/value pairs that provide details regarding the error. AspectValueDistribution: type: object properties: localizedAspectValue: type: string description: The value of an aspect. For example, Red is a value for the aspect Color. matchCount: type: integer description: The number of items with this aspect. format: int32 refinementHref: type: string description: A HATEOAS reference for this aspect. description: The container that defines the fields for the conditions refinements. This container is returned when fieldgroups is set to ASPECT_REFINEMENTS or FULL in the request. SearchByImageRequest: type: object properties: image: type: string description: The Base64 string of the image. To get the Base64 image string, you can use sites such as https://codebeautify.org/image-to-base64-converter. description: The type that defines the fields for the image information. securitySchemes: api_auth: type: oauth2 description: The security definitions for this API. Please check individual operations for applicable scopes. flows: authorizationCode: authorizationUrl: https://auth.ebay.com/oauth2/authorize tokenUrl: https://api.ebay.com/identity/v1/oauth2/token scopes: https://api.ebay.com/oauth/api_scope/sell.account.readonly: View your account settings https://api.ebay.com/oauth/api_scope/sell.account: View and manage your account settings

Pagination and sort controls

Restrictions

URL Encoding for Parameters

Restrictions