api-specs/buy_browse_v1_oas3.yaml
openapi: 3.0.0
info:
title: Browse API
description: '<p>The Browse API has the following resources:</p> <ul> <li><b> item_summary: </b> Lets shoppers search for specific items by keyword, GTIN, category, charity, product, or item aspects and refine the results by using filters, such as aspects, compatibility, and fields values.</li> <li><b> search_by_image: </b><a href="https://developer.ebay.com/api-docs/static/versioning.html#experimental " target="_blank"><img src="/cms/img/docs/experimental-icon.svg" class="legend-icon experimental-icon" alt="Experimental Release" title="Experimental Release" /> (Experimental)</a> Lets shoppers search for specific items by image. You can refine the results by using URI parameters and filters.</li> <li><b> item: </b> <ul><li>Lets you retrieve the details of a specific item or all the items in an item group, which is an item with variations such as color and size and check if a product is compatible with the specified item, such as if a specific car is compatible with a specific part.</li> <li>Provides a bridge between the eBay legacy APIs, such as <b> Finding</b>, and the RESTful APIs, which use different formats for the item IDs.</li> </ul> </li> <li> <b> shopping_cart: </b> <a href="https://developer.ebay.com/api-docs/static/versioning.html#experimental " target="_blank"><img src="/cms/img/docs/experimental-icon.svg" class="legend-icon experimental-icon" alt="Experimental Release" title="Experimental Release" /> (Experimental)</a> <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited " target="_blank"> <img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" title="Limited Release" alt="Limited Release" />(Limited Release)</a> Provides the ability for eBay members to see the contents of their eBay cart, and add, remove, and change the quantity of items in their eBay cart. <b> Note: </b> This resource is not available in the eBay API Explorer.</li></ul> <p>The <b> item_summary</b>, <b> search_by_image</b>, and <b> item</b> resource calls require an <a href="/api-docs/static/oauth-client-credentials-grant.html">Application access token</a>. The <b> shopping_cart</b> resource calls require a <a href="/api-docs/static/oauth-authorization-code-grant.html">User access token</a>.</p>'
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.18.0
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /buy/browse/v1
paths:
/item_summary/search:
get:
tags:
- item_summary
description: <p>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.</p><span class="tablenote"><p><b>Note:</b> 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.</p><p>Note that an auction listing enabled with the 'Buy it Now' feature will initially show AUCTION and FIXED_PRICE as buying options, but if/when that auction listing receives a qualifying bid, only AUCTION would remain as a buying option. If this happens, the buyingOptions filter would need to be used to retrieve that auction listing.</p></span><p>This method also supports the following:<ul><li>Filtering by the value of one or multiple fields, such as listing format, item condition, price range, location, and more. For the fields supported by this method, see the <a href="#uri.filter">filter</a> parameter.</li><li>Retrieving the refinements (metadata) of an item , such as item aspects (color, brand), condition, category, etc. using the <a href="#uri.fieldgroups">fieldgroups</a> parameter.</li><li>Filtering by item aspects and other refinements using the <a href="#uri.aspect_filter">aspect_filter</a> parameter. </li> <li>Filtering for items that are compatible with a specific product, using the <a href="#uri.compatibility_filter">compatibility_filter</a> parameter.</li><li>Creating aspects histograms, which enables shoppers to drill down in each refinement narrowing the search results.</li></ul></p><p>For details and examples of these capabilities, see <a href="/api-docs/buy/static/api-browse.html">Browse API</a> in the Buying Integration Guide.</p><h3><b> Pagination and sort controls</b></h3><p>There are pagination controls (<b>limit</b> and <b>offset</b> fields) and <b> sort</b> query parameters that control/sort the data that is returned. By default, the results are sorted by "Best Match". For more information about Best Match, see the eBay help page <a href="https://pages.ebay.com/help/sell/searchstanding.html " target="_blank">Best Match</a>.</p><h3><b>URLs for this method</b></h3><p><ul><li><b>Production URL:</b><code>https://api.ebay.com/buy/browse/v1/item_summary/search?</code></li><li><b>Sandbox URL:</b><code>https://api.sandbox.ebay.com/buy/browse/v1/item_summary/search?</code></li></ul></p><h3><b> Request headers</b></h3> This method uses the <b>X-EBAY-C-ENDUSERCTX</b> request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, <a href="/api-docs/buy/static/api-browse.html#Headers">Request headers</a> in the Buying Integration Guide.<h3><b>Restrictions </b></h3> <p>This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p><span class="tablenote"><b>eBay Partner Network:</b> In order to receive a commission for your sales, you must use the URL returned in the <code>itemAffiliateWebUrl</code> field to forward your buyer to the ebay.com site.</span>
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. <br /><br />For example, the method below uses the category ID for Women's Clothing. This will return only items for a woman's red shirt.<br /><br /><code>/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}</code> <br /><br />To get a list of the aspect pairs and the category, which is returned in the <b>dominantCategoryId</b> field, set <b>fieldgroups</b> to <code>ASPECT_REFINEMENTS</code>. <br /><br /> <code>/buy/browse/v1/item_summary/search?q=shirt&fieldgroups=ASPECT_REFINEMENTS</code> <br /><br /><span class="tablenote"><b> Note:</b> 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. <br /><br />The following example shows the correct format for entering two brand names as aspect filter values, one of which contains a pipe symbol:<br /><br /><code>/buy/browse/v1/item_summary/search?limit=50&category_ids=3034&filter=buyingOptions:{AUCTION|FIXED_PRICE}&aspect_filter=categoryId:3034,Brand:{Bed\|Stü|Nike}</code></span><br /><br /><b>Required:</b> The category ID is required <i>twice</i>; once as a URI parameter and as part of the <b> aspect_filter</b>. 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.<br /><br /><b>Valid Values:</b> <code>KEYWORD</code>
required: false
schema:
type: string
- name: category_ids
in: query
description: '<a name="category_ids"></a>The category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs.<br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?category_ids=29792</code> <br /><br /><span class="tablenote"><b> Note: </b>Currently, you can pass in only one category ID per request.</span> <br /> <br />You can also use any combination of the <b> category_Ids</b>, <b> epid</b>, and <b> q</b> fields. This gives you additional control over the result set. <br /><br />For example, let''s say you are looking of a toy phone. If you search for "phone", the result set will be mobile phones because this is the "Best Match" for this search. But if you also include the toy category ID, the results will be what you wanted. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=phone&category_ids=220</code><br /> <br />The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site: <ul> <li>Use the <a href="https://pages.ebay.com/sellerinformation/news/categorychanges.html " target="_blank">Category Changes page</a>.</li> <li>Use the Taxonomy API. For details see <a href="/api-docs/buy/buy-categories.html">Get Categories for Buy APIs</a>. </li> <li>Submit the following method to get the <b> dominantCategoryId</b> for an item. <br /><br /><code>/buy/browse/v1/item_summary/search?q=<em> keyword</em>&fieldgroups=ASPECT_REFINEMENTS </code></li></ul> <span class="tablenote"> <b> Note:</b> If a top-level (L1) category is specified, you <b> must</b> also include the <b> q</b> query parameter.</span> <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these)'
required: false
schema:
type: string
- name: charity_ids
in: query
description: 'The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities.<br /><br /> <b>For example:</b><br /><code>/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469</code><br /><br />The charity ID is the charity''s registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called "Charity Number". <ul><li>To find the charities eBay supports, you can search for a charity at <a href="https://charity.ebay.com/search " target="_blank">Charity Search </a> or go to <a href="https://www.ebay.com/b/Charity/bn_7114598164 " target="_blank">Charity Shop</a>.</li> <li>To find the charity ID of a specific charity, click on a charity and use the EIN number. For example, the charity ID for <a href="https://charity.ebay.com/charity/American-Red-Cross/3843 " target="_blank">American Red Cross</a>, is <code>530196605</code>.</li></ul> You can also use any combination of the <code>category_Ids</code> and <code>q</code> fields with a <code>charity_Ids</code> to filter the result set. This gives you additional control over the result set. <br /><br /><b>Restriction: </b> This is supported only on the US and GB marketplaces.<br /><br /><b>Maximum: </b> 20 IDs <br /><br /><b>Required:</b> One ID'
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.<br /><br /><span class="tablenote"><b>Note:</b> The only products supported are cars, trucks, and motorcycles.</span><br />For example, if the keyword is <code>brakes</code> and <code>compatibility-filter=Year:2018;Make:BMW</code>, the items returned are items with brakes, 2018, or BMW in the title.<br /><br />The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the <a href="/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.compatibilityMatch"> CompatibilityMatchEnum</a> value that indicates how well the item matches the attributes.<br /><br /><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> See the <a href="/api-docs/buy/browse/resources/item_summary/methods/search#s0-1-21-6-7-7-6-ReturnItemsthatareCompatiblewiththeKeywordandVehicle-9">Samples</a> section for a detailed example.</span><br /><b>Best Practice:</b> Submit all of the <a href="/api-docs/buy/static/api-browse.html#product-attributes">product attributes</a> for the specific product.<br /><br />To find the attributes and values for a specific marketplace, you can use the <a href="/api-docs/commerce/taxonomy/resources/category_tree/methods/getCompatibilityProperties">getCompatibilityProperties</a> method in the <a href="/api-docs/commerce/taxonomy/resources/methods">Taxonomy API</a>.<br /><br />For more details, see <a href="/api-docs/buy/static/api-browse.html#Check">Check compatibility</a> in the Buy Integration Guide.<br /><br /><span class="tablenote"><b>Note:</b> Testing in Sandbox is only supported using mock data. See <a href="/api-docs/buy/static/api-browse.html#sbox-test">Testing search in the Sandbox</a> for details.</span><br /><b>Required:</b><ul><li><b>q</b> (keyword)</li><li>One fitment supported category ID (such as <code>33559</code> Brakes)</li><li>At least one <a href="/api-docs/buy/static/api-browse.html#product-attributes">product attribute</a> name/value pair</li></ul> 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. <br /><br />The <b> Marketing</b> API <b>getMerchandisedProducts</b> method and the <b>Browse</b> API <b> getItem</b>, <b> getItemByLegacyId</b>, and <b> getItemsByItemGroup</b> calls return the ePID of the product. You can also use the <a href="/api-docs/commerce/catalog/resources/product_summary/methods/search">product_summary/search</a> method in the <b>Catalog</b> API to search for the ePID of the product. <br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?epid=15032</code> <br /><br /><b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these)'
required: false
schema:
type: string
- name: fieldgroups
in: query
description: This field is a comma separated list of values that lets you control what is returned in the response. The default is <b> MATCHING_ITEMS</b>, 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.<br /><br /><b>Valid Values:</b> <ul><li><b> ASPECT_REFINEMENTS</b> - This returns the <a href="#response.refinement.aspectDistributions">aspectDistributions</a> container, which has the <b>dominantCategoryId</b>, <b>matchCount</b>, and <b>refinementHref</b> for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be <b>Model Year</b>, <b>Exterior Color</b>, <b>Vehicle Mileage</b>, etc.<br /><br /><span class="tablenote"> <b>Note:</b> ASPECT_REFINEMENTS are category specific.</span></li><li><b>BUYING_OPTION_REFINEMENTS</b> - This returns the <a href="#response.refinement.buyingOptionDistributions">buyingOptionDistributions</a> container, which has the <b>matchCount</b> and <b>refinementHref</b> for <b>AUCTION</b>, <b>FIXED_PRICE</b> (Buy It Now), and <b>CLASSIFIED_AD</b> items.</li><li><b>CATEGORY_REFINEMENTS</b> - This returns the <a href="#response.refinement.categoryDistributions">categoryDistributions</a> container, which has the categories that the item is in.</li><li><b>CONDITION_REFINEMENTS</b> - This returns the <a href="#response.refinement.conditionDistributions">conditionDistributions</a> container, such as <b>NEW</b>, <b>USED</b>, etc. Within these groups are multiple states of the condition. For example, <b>New</b> can be New without tag, New in box, New without box, etc.</li><li><b>EXTENDED</b> - This returns the <a href="/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.shortDescription">shortDescription</a> field, which provides condition and item aspect information and the <a href="/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.itemLocation.city">itemLocation.city</a> field.</li><li><b>MATCHING_ITEMS</b> - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.</li><li><b>FULL</b> - This returns all the refinement containers and all the matching items.</li></ul>Code so that your app gracefully handles any future changes to this list.<br /><br /><b>Default:</b> 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. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]</code><br /><br />You can also combine filters. <br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}</code><br /><br /><span class="tablenote"><span style="color:#004680"><strong>Note:</strong></span> Refer to <a href="/api-docs/buy/static/ref-buy-browse-filters.html">Buy API Field Filters</a> for details and examples of all supported filters.</span> 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 the item as defined by <a href="https://www.gtin.info " target="_blank">https://www.gtin.info</a>. You can search only by UPC (Universal Product Code). If you have other formats of GTIN, you need to search by keyword. <br /><br /><b> For example: </b><br/><code> /buy/browse/v1/item_summary/search?gtin=099482432621</code> <br /><br /> <b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these)'
required: false
schema:
type: string
- name: limit
in: query
description: The number of items from the result set returned in a single page. <br /><br /><span class="tablenote"><b>Note:</b> If a value is set in the <b>limit</b> field, the value of <b>offset</b> must be either zero or a multiple of the <b>limit</b> value. An error is returned for invalid values of <b>offset</b>.</span> <br /><br /><b>Default:</b> 50 <br /><br /><b>Maximum number of items per page (limit):</b> 200 <br /><br /><b>Maximum number of items in a result set:</b> 10,000
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 <b>limit</b> field to control the pagination of the output. <br /><br />For example, if <b>offset</b> is 0 and <b>limit</b> is 10, the method will retrieve items 1-10 from the list of items returned; if <b>offset</b> is 10 and <b>limit</b> is 10, the method will retrieve items 11-20 from the list of items returned. <br /><br /><span class="tablenote"><b>Note:</b> The value of <b>offset</b> must be either zero or a multiple of the value set in the <b>limit</b> field. An empty result set is returned for invalid values of <b>offset</b>.</span> <br /><br /><b> Valid Values</b>: 0-10,000 (inclusive) <br /><br /><b>Default:</b> 0 <br /><br /><b>Maximum number of items returned:</b> 10,000'
required: false
schema:
type: string
- name: q
in: query
description: 'A string consisting of one or more keywords that are used to search for items on eBay. The keywords are handled as follows:<ul><li>If the keywords are separated by a space, it is treated as an AND. In the following example, the query returns items that have iphone <b>AND</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=iphone ipad</code><br/><br /></li><li>If the keywords are input using parentheses and separated by a comma, or if they are URL-encoded, it is treated as an OR. In the following examples, the query returns items that have iphone <b>OR</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=(iphone, ipad)</code><br /><br /><code>/buy/browse/v1/item_summary/search?q=%28iphone%2c%20ipad%29</code><br /><br /></li></ul><b>Restriction:</b> The <code>*</code> wildcard character is <b>not</b> allowed in this field.<br /><br /><b>Required:</b> The method must have <b>category_ids</b>, <b>epid</b>, <b>gtin</b>, or <b>q</b> (or any combination of these). '
required: false
schema:
type: string
- name: sort
in: query
description: 'The order and field name that is used to sort the items. <br /><br />You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen (<code>-</code>) before the name of the sorting option. If no <b>sort</b> parameter is submitted, the result set is sorted by "<a href="https://pages.ebay.com/help/sell/searchstanding.html " target="_blank">Best Match</a>".<br /><br />Here are some examples showing how to use the <b>sort</b> query parameter:<br /><ul><li><b><code>sort=distance</code></b> - This sorts by <i>distance</i> in ascending order (shortest distance first). This sorting option is only applicable if the <a href="/api-docs/buy/static/ref-buy-browse-filters.html#pickupCountry">pickup</a> filters are used, and only ascending order is supported.</li><li><b><code>sort=-price</code></b> - This sorts by <i>price + shipping cost</i> in descending order (highest price first). This sorting option (by <i>price</i>) is only guaranteed to work correctly if the <b>X-EBAY-C-ENDUSERCTX</b> request header is used, with the <b>contextualLocation</b> parameter being used to set the delivery country and postal code. Here is an example of how this header would be used to do this (note the URL encoding):<br /><br /><code>X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406</code><br /></li><li><b><code>sort=newlyListed</code></b> - This sorts by <i>listing date</i> (most recently listed/newest items first).</li><li><b><code>sort=endingSoonest</code></b> - This sorts by <i>date/time</i> the listing ends (listings nearest to end date/time first).</li></ul><b>Default:</b> Ascending 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
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}'
'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:
- search_by_image
description: '<img src="/cms/img/docs/experimental-icon.svg" class="legend-icon experimental-icon" alt="Experimental Release" title="Experimental Release"> This is an <a href="https://developer.ebay.com/api-docs/static/versioning.html#experimental ">Experimental</a> method. <p>This method searches for eBay items based on a image and retrieves summaries of the items. You pass in a Base64 image in the request payload and can refine the search by category, or eBay product ID (ePID), or a combination of these using URI parameters. <br /><br />To get the Base64 image string, you can use sites such as <a href="https://codebeautify.org/image-to-base64-converter " target="_blank">https://codebeautify.org/image-to-base64-converter</a>. </p><p>This method also supports the following: <ul> <li>Filtering by the value of one or multiple fields, such as listing format, item condition, price range, location, and more. For the fields supported by this method, see the <a href="#uri.filter">filter</a> parameter.</li><li>Filtering by item aspects using the <a href="#uri.aspect_filter">aspect_filter</a> parameter. </li> </ul></p> <p>For details and examples of these capabilities, see <a href="/api-docs/buy/static/api-browse.html">Browse API</a> in the Buying Integration Guide.</p><h3><b>Pagination and sort controls</b></h3> <p>There are pagination controls (<b>limit</b> and <b>offset</b> fields) and <b> sort</b> query parameters that control/sort the data that is returned. By default, the results are sorted by "Best Match". For more information about Best Match, see the eBay help page <a href="https://pages.ebay.com/help/sell/searchstanding.html " target="_blank">Best Match</a>. </p> <h3><b> URLs for this method</b></h3><p><ul><li><b>Production URL:</b> <code>https://api.ebay.com/buy/browse/v1/item_summary/search_by_image?</code></li><li><b> Sandbox URL: </b>Due to the data available, this method is not supported in the eBay Sandbox. To test your integration, use the Production URL.</li></ul></p><h3><b> Request headers</b></h3> This method uses the <b>X-EBAY-C-ENDUSERCTX</b> request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, <a href="/api-docs/buy/static/api-browse.html#Headers">Request headers</a> in the Buying Integration Guide. <h3><b>URL Encoding for Parameters</b></h3> <p>Query parameter values need to be URL encoded. For details, see <a href="/api-docs/static/rest-request-components.html#parameters">URL encoding query parameter values</a>. For readability, code examples in this document have not been URL encoded.</p> <h3><b>Restrictions </b></h3> <p>This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p> <span class="tablenote"><b>eBay Partner Network: </b> In order to receive a commission for your sales, you must use the URL returned in the <code>itemAffiliateWebUrl</code> field to forward your buyer to the ebay.com site. </span> '
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. <br /><br />For example, the method below uses the category ID for Women''s Clothing. This will return only items for a woman''s red shirt.<br /><br /><code>category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}</code> <br /><br /><b>Required: </b> The category ID is required <i>twice</i>; once as a URI parameter and as part of the <b> aspect_filter</b>. 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. This field can have one category ID or a comma separated list of IDs. <br /><br /><span class="tablenote"><b> Note: </b>Currently, you can pass in only one category ID per request.</span> <br /> <br />You can also use any combination of the <b> category_Ids</b> and <b> epid</b> fields. This gives you additional control over the result set.<br /> <br />The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site: <ul> <li>Use the <a href="https://pages.ebay.com/sellerinformation/news/categorychanges.html " target="_blank">Category Changes page</a>.</li> <li>Use the Taxonomy API. For details see <a href="/api-docs/buy/buy-categories.html">Get Categories for Buy APIs</a>. </li> <li>Submit the following method to get the <b> dominantCategoryId</b> for an item. <br /><code>/buy/browse/v1/item_summary/search?q=<em > keyword</em>&fieldgroups=ASPECT_REFINEMENTS </code></li></ul> <b> Required: </b> The method must have <b> category_ids</b> or <b> epid</b> (or any combination of these)'
required: false
schema:
type: string
- name: charity_ids
in: query
description: 'The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities.<br /><br /> <b>For example:</b><br /><code>/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469</code><br /><br />The charity ID is the charity''s registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called "Charity Number". <ul><li>To find the charities eBay supports, you can search for a charity at <a href="https://charity.ebay.com/search " target="_blank">Charity Search </a> or go to <a href="https://www.ebay.com/b/Charity/bn_7114598164 " target="_blank">Charity Shop</a>.</li> <li>To find the charity ID of a specific charity, click on a charity and use the EIN number. For example, the charity ID for <a href="https://charity.ebay.com/charity/American-Red-Cross/3843 " target="_blank">American Red Cross</a>, is <code>530196605</code>.</li></ul> You can also use any combination of the <code>category_Ids</code> and <code>q</code> fields with a <code>charity_Ids</code> to filter the result set. This gives you additional control over the result set. <br /><br /><b>Restriction: </b> This is supported only on the US and GB marketplaces.<br /><br /><b>Maximum: </b> 20 IDs <br /><br /><b>Required:</b> One ID'
required: false
schema:
type: string
- name: fieldgroups
in: query
description: This field is a comma separated list of values that lets you control what is returned in the response. The default is <b>MATCHING_ITEMS</b>, 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.<br /><br /><b>Valid Values:</b><ul><li><b>ASPECT_REFINEMENTS</b> - This returns the <a href="#response.refinement.aspectDistributions">aspectDistributions</a> container, which has the <b>dominantCategoryId</b>, <b>matchCount</b>, and <b>refinementHref</b> for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be <b>Model Year</b>, <b>Exterior Color</b>, <b>Vehicle Mileage</b>, etc.<br /><br /><span class="tablenote"><b>Note:</b> ASPECT_REFINEMENTS are category specific.</span></li><li><b>BUYING_OPTION_REFINEMENTS</b> - This returns the <a href="#response.refinement.buyingOptionDistributions">buyingOptionDistributions</a> container, which has the <b>matchCount</b> and <b>refinementHref</b> for <b>AUCTION</b>, <b>FIXED_PRICE</b> (Buy It Now), and <b>CLASSIFIED_AD</b> items.</li><li><b>CATEGORY_REFINEMENTS</b> - This returns the <a href="#response.refinement.categoryDistributions">categoryDistributions</a> container, which has the categories that the item is in.</li><li><b>CONDITION_REFINEMENTS</b> - This returns the <a href="#response.refinement.conditionDistributions">conditionDistributions</a> container, such as <b> NEW</b>, <b> USED</b>, etc. Within these groups are multiple states of the condition. For example, <b>New</b> can be New without tag, New in box, New without box, etc.</li><li><b>EXTENDED</b> - This returns the <a href="/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.shortDescription">shortDescription</a> field, which provides condition and item aspect information and the <a href="/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.itemLocation.city">itemLocation.city</a> field.</li><li><b>MATCHING_ITEMS</b> - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.</li><li><b>FULL</b> - This returns all the refinement containers and all the matching items.</li></ul>Code so that your app gracefully handles any future changes to this list.<br /><br /><b>Default:</b> 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. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]</code><br /><br />You can also combine filters. <br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}</code><br /><br /><span class="tablenote"><span style="color:#004680"><strong>Note:</strong></span> Refer to <a href="/api-docs/buy/static/ref-buy-browse-filters.html">Buy API Field Filters</a> for details and examples of all supported filters.</span> 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. <br /><br /><b> Default:</b> 50 <br /> <br /><b> Maximum number of items per page (limit): </b>200 <br /> <br /> <b> Maximum number of items in a result set: </b> 10,000'
required: false
schema:
type: string
- name: offset
in: query
description: 'The number of items to skip in the result set. This is used with the <b> limit</b> field to control the pagination of the output. <br /><br />If <b> offset</b> is 0 and <b> limit</b> is 10, the method will retrieve items 1-10 from the list of items returned, if <b> offset</b> is 10 and <b> limit</b> is 10, the method will retrieve items 11 thru 20 from the list of items returned. <br /><br /><b> Valid Values</b>: 0-10,000 (inclusive) <br /> <br /> <b> Default:</b> 0 <br /> <br /> <b> Maximum number of items returned: </b> 10,000 '
required: false
schema:
type: string
- name: sort
in: query
description: 'The order and field name that is used to sort the items. <br /><br />You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen (<code>-</code>) before the name of the sorting option. If no <b>sort</b> parameter is submitted, the result set is sorted by "<a href="https://pages.ebay.com/help/sell/searchstanding.html " target="_blank">Best Match</a>".<br /><br />Here are some examples showing how to use the <b>sort</b> query parameter:<br /><ul><li><b><code>sort=distance</code></b> - This sorts by <i>distance</i> in ascending order (shortest distance first). This sorting option is only applicable if the <a href="/api-docs/buy/static/ref-buy-browse-filters.html#pickupCountry">pickup</a> filters are used, and only ascending order is supported.</li><li><b><code>sort=-price</code></b> - This sorts by <i>price + shipping cost</i> in descending order (highest price first). This sorting option (by <i>price</i>) is only guaranteed to work correctly if the <b>X-EBAY-C-ENDUSERCTX</b> request header is used, with the <b>contextualLocation</b> parameter being used to set the delivery country and postal code. Here is an example of how this header would be used to do this (note the URL encoding):<br /><br /><code>X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406</code><br /></li><li><b><code>sort=newlyListed</code></b> - This sorts by <i>listing date</i> (most recently listed/newest items first).</li><li><b><code>sort=endingSoonest</code></b> - This sorts by <i>date/time</i> the listing ends (listings nearest to end date/time first).</li></ul><b>Default:</b> Ascending 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
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}'
'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/{item_id}:
get:
tags:
- item
description: '<p>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.</p><p>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. You can do this easily by setting the <b> fieldgroups</b> URI parameter. This parameter lets you control what is returned in the response.</p> <p>Setting <b> fieldgroups</b> to <code>COMPACT</code> reduces the response to only those fields that you need in order to check if any item detail has changed. Setting <b> fieldgroups</b> to <code>PRODUCT</code>, adds additional fields to the default response that return information about the product of the item. You can use either <code>COMPACT</code> or <code>PRODUCT</code> but not both. For more information, see <a href="/api-docs/buy/browse/resources/item/methods/getItem#uri.fieldgroups">fieldgroups</a>.</p> <h3>URLs for this method</h3> <p><ul> <li><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/item/{item_id}</code></li> <li><b> Sandbox URL: </b><code>https://api.sandbox.ebay.com/buy/browse/v1/item/{item_id}</code></li> </ul> </p> <h3><b> Request headers</b></h3> This method uses the <b>X-EBAY-C-ENDUSERCTX</b> request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, <a href="/api-docs/buy/static/api-browse.html#Headers">Request headers</a> in the Buying Integration Guide. <h3><b> Restrictions </b></h3> <p>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p> <span class="tablenote"><b>eBay Partner Network: </b> In order to be commissioned for your sales, you must use the URL returned in the <code>itemAffiliateWebUrl</code> field to forward your buyer to the ebay.com site. </span>'
operationId: getItem
parameters:
- name: fieldgroups
in: query
description: 'This parameter lets you control what is returned in the response. If you do not set this field, the method returns all the details of the item. <br /> <br /> <b> Valid Values: </b> <ul> <li> <b> PRODUCT</b> - This adds the <code>additionalImages</code>, <code>additionalProductIdentities</code>, <code>aspectGroups</code>, <code>description</code>, <code>gtins</code>, <code>image</code>, and <code>title</code> product fields to the response, which describe the product associated with the item. See <a href="/api-docs/buy/browse/resources/item/methods/getItem#response.product">Product</a> for more information about these fields.</li> <li><b> COMPACT</b> - This 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. <ul> <li> <b> itemId</b> - The identifier of the item.</li> <li><b>bidCount</b> - This integer value indicates the total number of bids that have been placed against an auction item.</li> <li><b>currentBidPrice</b> - This container shows the current highest bid for an auction item. This container will only be returned for auction items.</li> <li><b>eligibleForInlineCheckout</b> - This parameter returns items based on whether or not the items can be purchased using the Buy <a href="/api-docs/buy/order/resources/methods">Order API</a>. <ul> <li>If the value of this field is <code>true</code>, this indicates that the item can be purchased using the <b> Order API</b>. </li> <li>If the value of this field is <code>false</code>, this indicates that the item cannot be purchased using the <b> Order API</b> and must be purchased on the eBay site.</li> </ul> <li><b> estimatedAvailabilities</b> - Returns the item availability information, which is based on the item''s quantity. <b> Note:</b> Changes in quantity are not tracked by <b>sellerItemRevision</b>.</li> <li><b>itemAffiliateWebURL</b> - The URL of the View Item page of the item, which includes the affiliate tracking ID. This field is only returned if the eBay partner enables affiliate tracking for the item by including the <code>X-EBAY-C-ENDUSERCTX</code> request header in the method.</li><li><b>itemCreationDate</b> - This is a timestamp that indicates the date and time an item listing was created.</li> <li><b>itemEndDate</b> - This is the scheduled end time of the listing.</li> <li><b>ItemWebURL</b> - The URL of the View Item page of the item. This enables you to include a "Report Item on eBay" link that takes the buyer to the View Item page on eBay. From there they can report any issues regarding this item to eBay.</li> <li><b>legacyItemId</b> - 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.</li> <li><b>minimumPriceToBid</b> - This container shows the minimum bid amount that would be accepted as a qualifying bid in an auction listing. This container will only be returned for auction items.</li> <li><b>price</b> - This is tracked by the revision ID but is returned here to enable you to quickly verify the price of the item.</li> <li><b>priorityListing</b> - This field is returned as <code>true</code> 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.</li> <li><b>reservePriceMet</b> - This field indicates whether or not an auction''s reserve price (if set by the seller) has been met yet. This field will only be returned for auction items.</li> <li><b> sellerItemRevision</b> - An identifier generated/incremented when a seller revises the item. The following are the two types of item revisions: <ul> <li><b> Seller changes</b>, such as changing the title</li> <li> <b> eBay system changes</b>, such as changing the quantity when an item is purchased.</li> </ul> This ID is changed <em>only</em> when the seller makes a change to the item. This means you cannot use this value to determine if the quantity has changed. To check if the quantity has changed, use <b> estimatedAvailabilities.</b></li> <li><b>shippingOptions</b> - A container for the cost, carrier, and other details of shipping options.</li> <li><b>taxes</b> - A container for the tax information for the item, such as the tax jurisdiction, the tax percentage, and the tax type.</li> <li><b> topRatedBuyingExperience</b> - A boolean value indicating if this item is a top-rated plus item. A change in the item''s top rated plus standing is not tracked by the revision ID. See <a href="/api-docs/buy/browse/resources/item/methods/getItem#response.topRatedBuyingExperience">topRatedBuyingExperience</a> for more information.</li> <li><b>uniqueBidderCount</b> - This integer value indicates the number of different eBay users who have placed one or more bids on an auction item. This field is only applicable to auction items.</li></ul> <b> For Example</b> <br /> <br />To check if a stored item''s information is current, do following. <ol> <li>Pass in the item ID and set <b> fieldgroups</b> to COMPACT. <br /> <br /><code>item/v1|4**********8|0?fieldgroups=COMPACT</code> </li> <li>Do one of the following: <ul> <li>If the <b> sellerItemRevision</b> field is returned and you <em>haven''t</em> stored a revision number for this item, record the number and pass in the item ID in the <b> getItem</b> method to get the latest information.</li> <li>If the revision number is different from the value you have stored, update the value and pass in the item ID in the <b> getItem</b> method to get the latest information.</li> <li>If the <b> sellerItemRevision</b> field is <em>not</em> returned or has not changed, where needed, update the item information with the information returned in the response.</li> </ul> </li> </ol></li> </ul> </ul> <p><b> Maximum value: </b> 1 <br />If more than one values is specified, the first value will be used.'
required: false
schema:
type: string
- name: item_id
in: path
description: 'The eBay RESTful identifier of an item. This ID is returned by the <b> Browse</b> and <b> Feed</b> API methods. <br /><br /> <b> RESTful Item ID Format: </b><code>v1</code>|<code><i>#</i></code>|<code><i>#</i></code> <br />For example: <code>v1|2**********2|0</code> or <code>v1|1**********2|4**********2</code> <br /><br />For more information about item ID for RESTful APIs, see the <a href="/api-docs/buy/static/api-browse.html#Legacy">Legacy API compatibility</a> section of the <i>Buy APIs Overview</i>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
x-response-codes:
errors:
'11001':
domain: API_BROWSE
category: REQUEST
description: The specified item ID was not found.
'11002':
domain: API_BROWSE
category: REQUEST
description: The specified item group was not found.
'11004':
domain: API_BROWSE
category: REQUEST
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':
domain: API_BROWSE
category: REQUEST
description: The item group ID is invalid. Use {itemHref} to get the item details.
'11008':
domain: API_BROWSE
category: REQUEST
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.
'11502':
domain: API_BROWSE
category: APPLICATION
description: There was a problem extracting product information for this Item. Please try again.
'11508':
domain: API_BROWSE
category: APPLICATION
description: This seller is currently away. If you make a purchase, please allow additional time for your order to be processed.
'11509':
domain: API_BROWSE
category: APPLICATION
description: This seller is currently away until {sellerReturnDate}. If you make a purchase, please allow additional time for your order to be processed.
'400':
description: Bad Request
x-response-codes:
errors:
'11011':
domain: API_BROWSE
category: REQUEST
description: 'The marketplace value {marketplaceId} is not supported. The supported values are: {allowedMarketplaces}'
'11012':
domain: API_BROWSE
category: REQUEST
description: The specified item IDs are invalid, or the format of the specified values are invalid.
'11013':
domain: API_BROWSE
category: REQUEST
description: The specified group IDs are invalid, or the format of the specified values are invalid.
'11014':
domain: API_BROWSE
category: REQUEST
description: An item_ids and an item_group_ids list cannot be used at same time. Please use only one of these lists.
'11015':
domain: API_BROWSE
category: REQUEST
description: The maximum number of item ids has been exceeded. Please reduce the number of item ids to {maxAllowedItemIds} or less.
'11016':
domain: API_BROWSE
category: REQUEST
description: The maximum number of item group IDs has been exceeded. Please reduce the number of item group ids to {maxAllowedItemGroupIds} or less.
'11501':
domain: API_BROWSE
category: REQUEST
description: 'The ''fieldgroups'' value {fieldgroups} is invalid. The supported fieldgroups are: {supportedFieldgroups}'
'404':
description: Not Found
'409':
description: Conflict
'500':
description: Internal Server Error
x-response-codes:
errors:
'11000':
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/get_item_by_legacy_id:
get:
tags:
- item
description: ' <p>This method is a bridge between the eBay legacy APIs, such as <b> Shopping</b>, and <b> Finding</b> 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.</p> <p>For more information about how to use legacy ids with the Buy APIs, see <a href="/api-docs/buy/static/api-browse.html#Legacy">Legacy API compatibility</a> in the Buying Integration guide.</p> <p>This method returns the item details and requires you to pass in either the item ID of a non-variation item or the item ids of both the parent and child of an item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.</p> <p>When an item group is created, one of the item variations, such as the red shirt size L, is chosen as the "parent". All the other items in the group are the children, such as the blue shirt size L, red shirt size M, etc.</p> <p>The <b> fieldgroups</b> URI parameter lets you control what is returned in the response. Setting <b> fieldgroups</b> to <code>PRODUCT</code>, adds additional fields to the default response that return information about the product of the item. For more information, see <a href="/api-docs/buy/browse/resources/item/methods/getItemByLegacyItem#uri.fieldgroups">fieldgroups</a>.</p> <h3>URLs for this method</h3> <p><ul> <li><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/item/get_item_by_legacy_id?</code></li> <li><b> Sandbox URL: </b><code>https://api.sandbox.ebay.com/buy/browse/v1/item/get_item_by_legacy_id?</code></li> </ul> </p> <h3><b> Request headers</b></h3> This method uses the <b>X-EBAY-C-ENDUSERCTX</b> request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, <a href="/api-docs/buy/static/api-browse.html#Headers">Request headers</a> in the Buying Integration Guide. <h3><b> Restrictions </b></h3> <p>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p> <span class="tablenote"><b>eBay Partner Network: </b> In order to be commissioned for your sales, you must use the URL returned in the <code>itemAffiliateWebUrl</code> field to forward your buyer to the ebay.com site. </span>'
operationId: getItemByLegacyId
parameters:
- name: fieldgroups
in: query
description: 'This field lets you control what is returned in the response. If you do not set this field, the method returns all the details of the item. <b> Note</b>: In this method, the only value supported is <code>PRODUCT</code>. <p><b> Valid Values: </b><br /><br /> <b> PRODUCT</b> - This adds the <code>additionalImages</code>, <code>additionalProductIdentities</code>, <code>aspectGroups</code>, <code>description</code>, <code>gtins</code>, <code>image</code>, and <code>title</code> fields to the response, which describe the item''s product. See <a href="/api-docs/buy/browse/resources/item/methods/getItemByLegacyItem#response.product">Product</a> for more information about these fields. <br /><br />Code so that your app gracefully handles any future changes to this list.'
required: false
schema:
type: string
- name: legacy_item_id
in: query
description: 'Specifies either: <ul> <li>The legacy item ID of an item that is <em>not</em> part of a group. </li> <li>The legacy item ID of a group, which is the ID of the "parent" of the group of items. <br /> <br /><span class="tablenote"> <b> Note: </b> If you pass in a group ID, you must also use the <b> legacy_variation_id</b> field and pass in the legacy ID of the specific item variation (child ID).</span></li></ul> Legacy ids are returned by APIs, such as the <a href="https://developer.ebay.com/devzone/finding/callref/index.html " target="_blank">Finding API</a>. <br /><br />The following is an example of using the value of the <b> ItemID</b> field for a specific item from Finding to get the RESTful <b> itemId</b> value. <br /> <br /> <code> browse/v1/item/get_item_by_legacy_id?legacy_item_id=1**********9 </code><br /><br /><b> Maximum: </b> 1'
required: true
schema:
type: string
- name: legacy_variation_id
in: query
description: 'Specifies the legacy item ID of a specific item in an item group, such as the red shirt size L. <br /><br />Legacy ids are returned by APIs, such as the <a href="https://developer.ebay.com/devzone/finding/callref/index.html " target="_blank">Finding API</a>. <br /><br /><b> Maximum: </b> 1 <br /><b> Requirement: </b> You must <b> always</b> pass in the <b> legacy_item_id </b> with the <b> legacy_variation_id</b>'
required: false
schema:
type: string
- name: legacy_variation_sku
in: query
description: 'Specifics the legacy SKU of the item. SKU are item ids created by the seller. <br /><br />Legacy SKUs are returned by eBay the <a href="https://developer.ebay.com/Devzone/shopping/docs/CallRef/index.html " target="_blank">Shopping API</a>. <br /><br />The following is an example of using the value of the <b> ItemID</b> and <b> SKU</b> fields to get the RESTful <b> itemId</b> value. <br /> <br /> <code> browse/v1/item/get_item_by_legacy_id?legacy_item_id=1**********9&legacy_variation_sku=V**********M</code><br /><br /><b> Maximum: </b> 1 <br /><b> Requirement: </b> You must <b> always</b> pass in the <b> legacy_item_id </b> with the <b> legacy_variation_sku</b>'
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
x-response-codes:
errors:
'11502':
domain: API_BROWSE
category: APPLICATION
description: There was a problem extracting product information for this Item. Please try again.
'11508':
domain: API_BROWSE
category: APPLICATION
description: This seller is currently away. If you make a purchase, please allow additional time for your order to be processed.
'11509':
domain: API_BROWSE
category: APPLICATION
description: This seller is currently away until {sellerReturnDate}. If you make a purchase, please allow additional time for your order to be processed.
'400':
description: Bad Request
x-response-codes:
errors:
'11003':
domain: API_BROWSE
category: REQUEST
description: The specified legacy item ID was not found.
'11004':
domain: API_BROWSE
category: REQUEST
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.
'11006':
domain: API_BROWSE
category: REQUEST
description: The legacy ID is invalid. Use {itemGroupHref} to get the item group details.
'11009':
domain: API_BROWSE
category: REQUEST
description: The legacy variation sku is invalid.
'11010':
domain: API_BROWSE
category: REQUEST
description: You cannot submit legacy_variation_sku and legacy_variation_id in the same request. For help, see the documentation.
'11011':
domain: API_BROWSE
category: REQUEST
description: 'The marketplace value {marketplaceId} is not supported. The supported values are: {allowedMarketplaces}'
'404':
description: Not Found
'409':
description: Conflict
'500':
description: Internal Server Error
x-response-codes:
errors:
'11000':
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/:
get:
tags:
- item
description: 'This method retrieves the details of specific items that the buyer needs to make a purchasing decision. <br><br><span class="tablenote"> <b>Note:</b> This is a <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited " target="_blank"> <img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" title="Limited Release" alt="Limited Release" />(Limited Release)</a> available only to select Partners. <br><br>For this method, only the following fields are returned: <code>bidCount</code>, <code>currentBidPrice</code>, <code>eligibleForInlineCheckout</code>, <code>enabledForGuestCheckout</code>, <code>estimatedAvailabilities</code>, <code>itemAffiliateWebUrl</code>, <code>itemCreationDate</code>, <code>itemId</code>, <code>itemWebUrl</code>, <code>legacyItemId</code>, <code>minimumPriceToBid</code>, <code>price</code>, <code>priorityListing</code>, <code>reservePriceMet</code>, <code>sellerItemRevision</code>, <code>taxes</code>, <code>topRatedBuyingExperience</code>, and <code>uniqueBidderCount</code>.<br /><br />The array <code>shippingOptions</code>, which comprises multiple fields, is also returned.</span> <h3>URLs for this method</h3> <p><ul> <li><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/item?</code></li> <li><b> Sandbox URL: </b><code>https://api.sandbox.ebay.com/buy/browse/v1/item?</code></li> </ul> </p> <h3><b> Request headers</b></h3> This method uses the <b>X-EBAY-C-ENDUSERCTX</b> request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, <a href="/api-docs/buy/static/api-browse.html#Headers">Request headers</a> in the Buying Integration Guide. <h3><b> Restrictions </b></h3> <p>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p> <span class="tablenote"><b>eBay Partner Network:</b> 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. '
operationId: getItems
parameters:
- name: item_ids
in: query
description: 'A list of item IDs. Item IDs are the eBay RESTful identifier of items. <br><br><b> RESTful Item ID Format: </b><code>v1</code>|<code><i>#</i></code>|<code><i>#</i></code><br>For example: <code>v1|2**********2|0</code> or <code>v1|1**********2|4**********2</code> <br><br>In any given request, either item_ids or item_group_ids can be retrieved. Attempting to retrieve both will result in an error. <br><br> In a request, multiple item_ids can be passed as comma separated values.<br><br><b> Maximum allowed itemIDs: </b> 20 <br><br>For more information about item IDs for RESTful APIs, see the <a href="/api-docs/buy/static/api-browse.html#Legacy">Legacy API compatibility</a> section of the <i>Buy APIs Overview</i>.'
required: false
schema:
type: string
- name: item_group_ids
in: query
description: 'A list of item group IDs. Item group IDs are the eBay RESTful identifier of item groups. <br><br><b> RESTful Group Item ID Format: </b><code>############</code><br>For example: <code>3**********9</code><br><br>In any given request, either item_ids or item_group_ids can be retrieved. Attempting to retrieve both will result in an error.<br><br>In a request, multiple item_group_ids can be passed as comma separated values.<br><br><b> Maximum allowed itemGroupIDs: </b> 10 <br><br>'
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Items'
x-response-codes:
errors:
'11001':
domain: API_BROWSE
category: REQUEST
description: The specified item ID was not found.
'11002':
domain: API_BROWSE
category: REQUEST
description: The specified item group was not found.
'11004':
domain: API_BROWSE
category: REQUEST
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.
'11005':
domain: API_BROWSE
category: REQUEST
description: The item group ID is invalid. Use {itemHref} to get the item details.
'11008':
domain: API_BROWSE
category: REQUEST
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.
'11502':
domain: API_BROWSE
category: APPLICATION
description: There was a problem extracting product information for this item. Please try again.
'11508':
domain: API_BROWSE
category: APPLICATION
description: This seller is currently away. If you make a purchase, please allow additional time for your order to be processed.
'11509':
domain: API_BROWSE
category: APPLICATION
description: This seller is currently away until {sellerReturnDate}. If you make a purchase, please allow additional time for your order to be processed.
'400':
description: Bad Request
x-response-codes:
errors:
'11011':
domain: API_BROWSE
category: REQUEST
description: 'The marketplace value is not supported. The supported values are: {allowedMarketplaces}'
'11012':
domain: API_BROWSE
category: REQUEST
description: The specified item IDs are invalid, or the format of the specified values are invalid.
'11013':
domain: API_BROWSE
category: REQUEST
description: The specified group IDs are invalid, or the format of the specified values are invalid.
'11014':
domain: API_BROWSE
category: REQUEST
description: An item_ids and an item_group_ids list cannot be used at same time. Please use only one of these lists.
'11015':
domain: API_BROWSE
category: REQUEST
description: The maximum number of item IDs has been exceeded. Please reduce the number of item IDs to {maxAllowedItemIds} or less.
'11016':
domain: API_BROWSE
category: REQUEST
description: The maximum number of item group IDs has been exceeded. Please reduce the number of item group ids to {maxAllowedItemGroupIds} or less.
'11017':
domain: API_BROWSE
category: REQUEST
description: An item_ids or an item_group_ids list is required. Please use one of these lists.
'404':
description: Not Found
'409':
description: Conflict
'500':
description: Internal Server Error
x-response-codes:
errors:
'11000':
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/buy.item.bulk
/item/get_items_by_item_group:
get:
tags:
- item
description: ' <p>This method retrieves the details of the individual items in an item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. </p> <p>You pass in the item group ID as a URI parameter. You use this method to show the item details of items with multiple aspects, such as color, size, storage capacity, etc. </p> <p>This method returns two main containers; <b> items</b> and <b> commonDescriptions</b>. The <b> items</b> container has an array of containers with the details of each item in the group. The <b> commonDescriptions</b> container has an array of containers for a description and the item ids of all the items that have this exact description. Because items within an item group often have the same description, this decreases the size of the response. </p> <h3>URLs for this method</h3> <p><ul> <li><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/item/get_items_by_item_group?</code></li> <li><b> Sandbox URL: </b><code>https://api.sandbox.ebay.com/buy/browse/v1/item/get_items_by_item_group?</code></li> </ul> </p> <h3><b> Request headers</b></h3> This method uses the <b>X-EBAY-C-ENDUSERCTX</b> request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, <a href="/api-docs/buy/static/api-browse.html#Headers">Request headers</a> in the Buying Integration Guide. <h3><b> Restrictions </b></h3> <p>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p> <span class="tablenote"><b>eBay Partner Network: </b> In order to be commissioned for your sales, you must use the URL returned in the <code>itemAffiliateWebUrl</code> field to forward your buyer to the ebay.com site. </span> '
operationId: getItemsByItemGroup
parameters:
- name: item_group_id
in: query
description: 'Identifier of the item group to return. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. </p> <p>This ID is returned in the <b> itemGroupHref</b> field of the <a href="/api-docs/buy/browse/resources/item_summary/methods/search">search</a> and <a href="/api-docs/buy/browse/resources/item/methods/getItem">getItem</a> methods. <br /><br /><b> For Example: </b><code> https://api.ebay.com/buy/browse/v1/item/get_items_by_item_group?item_group_id=3**********6</code>'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ItemGroup'
x-response-codes:
errors:
'11508':
domain: API_BROWSE
category: APPLICATION
description: This seller is currently away. If you make a purchase, please allow additional time for your order to be processed.
'11509':
domain: API_BROWSE
category: APPLICATION
description: This seller is currently away until {sellerReturnDate}. If you make a purchase, please allow additional time for your order to be processed.
'400':
description: Bad Request
x-response-codes:
errors:
'11002':
domain: API_BROWSE
category: REQUEST
description: The specified item group was not found.
'11005':
domain: API_BROWSE
category: REQUEST
description: Item Group Id is invalid. Use {itemHref} to get the item details.
'11008':
domain: API_BROWSE
category: REQUEST
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':
domain: API_BROWSE
category: REQUEST
description: 'The marketplace value {marketplaceId} is not supported. The supported values are: {allowedMarketplaces}'
'404':
description: Not Found
'409':
description: Conflict
'500':
description: Internal Server Error
x-response-codes:
errors:
'11000':
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/{item_id}/check_compatibility:
post:
tags:
- item
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. <br /><br />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 in the <b> compatibilityProperties</b> container. If the call is successful, the response will be <b> COMPATIBLE</b>, <b> NOT_COMPATIBLE</b>, or <b> UNDETERMINED</b>. See <a href="/api-docs/buy/browse/resources/item/methods/checkCompatibility#response.compatibilityStatus">compatibilityStatus</a> for details. <br /><br /> <span class="tablenote"><b> Note: </b> The only products supported are cars, trucks, and motorcycles. </span><p> To find the attributes and values for a specific marketplace, you can use the compatibility methods in the <a href="/api-docs/commerce/taxonomy/resources/methods">Taxonomy API</a>. You can use this data to create menus to help buyers specify the product, such as their car.</p> <p> For more details and a list of the required attributes for the US marketplace that describe motor vehicles, see <a href="/api-docs/buy/static/api-browse.html#Check">Check compatibility</a> in the Buy Integration Guide</a>.</p> <p>For an example, see the <a href="/api-docs/buy/browse/resources/item/methods/checkCompatibility#h2-samples">Samples</a> section. </p> <h3>URLs for this method</h3> <p><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/item/{item_id}/check_compatibility</code> </p> <p><span class="tablenote"><b> Note: </b> This method is supported only on Production. </span></p> <h3><b> Restrictions </b></h3> <p>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p> '
operationId: checkCompatibility
parameters:
- name: item_id
in: path
description: 'The eBay RESTful identifier of an item (such as a part you want to check). This ID is returned by the <b> Browse</b> and <b> Feed</b> API methods. <br /><br /> <b> RESTful Item ID Format: </b><code>v1</code>|<code><i>#</i></code>|<code><i>#</i></code> <br />For example: <code>v1|2**********2|0</code> or <code>v1|1**********2|4**********2</code> <br /><br />For more information about item ID for RESTful APIs, see the <a href="/api-docs/buy/static/api-browse.html#Legacy">Legacy API compatibility</a> section of the <i>Buy APIs Overview</i>.'
required: true
schema:
type: string
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: 'The ID of the eBay marketplace you want to use. <b> Note: </b> This value is case sensitive.<br /><br />For example: <br /> <code>X-EBAY-C-MARKETPLACE-ID = EBAY_US</code> <br /><br /> For a list of supported sites see, <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompatibilityPayload'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CompatibilityResponse'
x-response-codes:
errors:
'11504':
domain: API_BROWSE
category: REQUEST
description: 'The following compatibilityProperties (attributes name/value pairs) are missing: {attributes}'
'400':
description: Bad Request
x-response-codes:
errors:
'11001':
domain: API_BROWSE
category: REQUEST
description: The specified item ID was not found.
'11011':
domain: API_BROWSE
category: REQUEST
description: 'The marketplace value {marketplaceId} is not supported. The supported values are: {allowedMarketplaces}'
'11503':
domain: API_BROWSE
category: REQUEST
description: The request is either empty or incomplete. For help, see the documentation for this call.
'11505':
domain: API_BROWSE
category: REQUEST
description: The item is not valid for compatibility validation.
'11506':
domain: API_BROWSE
category: REQUEST
description: The 'name' {compatibilityNames} appears more than once in the request.
'11507':
domain: API_BROWSE
category: REQUEST
description: The following name(s) in the request are not supported {attributes}.
'404':
description: Not Found
'409':
description: Conflict
'500':
description: Internal Server Error
x-response-codes:
errors:
'11000':
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
/shopping_cart/add_item:
post:
tags:
- shopping_cart
description: '<span class="tablenote"><b>Note: </b><img src="/cms/img/docs/experimental-icon.svg" class="legend-icon experimental-icon" alt="Experimental Release" title="Experimental Release" alt="Experimental Release" title="Experimental Release" /> This is an <a href="https://developer.ebay.com/api-docs/static/versioning.html#experimental">Experimental</a> method that is available as a <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited" target="_blank"> <img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" title="Limited Release" alt="Limited Release" />(Limited Release)</a> to select developers approved by business units.</span> <p>This method creates an eBay cart for the eBay member, if one does not exist, and adds items to that cart. Because a cart never expires, any item added to the cart will remain in the cart until it is removed. <br /><br />To use this method, you must submit a RESTful item ID and the quantity of the item. If the <b> quantity</b> value is greater than the number of available, the <b> quantity</b> value is changed to the number available and a warning is returned. For example, if there are 15 baseballs available and you set the <b> quantity</b> value to 50, the service automatically changes the value of <b>quantity</b> to 15. <br /><br />The response returns all the items in the eBay member''s cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. The quantity and state of an item changes often. If the item becomes "unavailable" such as, when the listing has ended or the item is out of stock, whether it has just been added to the cart or has been in the cart for some time, the item will be returned in the <b> unavailableCartItems</b> container.</p> <p span class="tablenote"><b>Note: </b>There are differences between how legacy APIs, such as Finding, and RESTful APIs, such as Browse, return the identifier of an "item" and what the item ID represents. If you have an item ID from one of the legacy APIs, you can use the legacy item ID with the <a href="/api-docs/buy/browse/resources/item/methods/getItemByLegacyId"> getItemByLegacyId</a> method to retrieve the RESTful ID for that item. For more information about how to use legacy IDs with the Buy APIs, see <a href="/api-docs/buy/static/api-browse.html#Legacy">Legacy API compatibility</a> in the Buying Integration guide.</p> <h3><b>URLs for this method</b></h3> <p><ul> <li><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/shopping_cart/add_item</code></li> <li><b> Sandbox URL: </b><code>https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/add_item</code> <br /><br /><b>Note: </b>This method is not available in the eBay API Explorer.</li> </ul> </p> <h3><b>Restrictions </b></h3> <ul> <li>This method can be used only for eBay members.</li> <li>You can only add FIXED_PRICE items. </li> </ul> <p>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p> '
operationId: addItem
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddCartItemInput'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteShopcartResponse'
x-response-codes:
errors:
'10004':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is not available for purchase. This can be for several reason such as, the listing has ended or the item is out of stock.
'10005':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is revised.
'10006':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} in your cart is not available in the quantity specified. The quantity of this item has been changed to the quantity that is currently available. Please review this change before proceeding to checkout.
'10020':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item {itemId}.
'10024':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item {itemId} because the seller does not ship to the buyer's location.
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'10001':
domain: API_BROWSE
category: REQUEST
description: 'The X-EBAY-C-MARKETPLACE-ID value is not supported. The supported values are: {supportedValues}.'
'10002':
domain: API_BROWSE
category: REQUEST
description: Insufficient permissions to fulfill the request.
'10007':
domain: API_BROWSE
category: REQUEST
description: 'The field: {field} is required. Add the field and resubmit the call.'
'10008':
domain: API_BROWSE
category: REQUEST
description: The item ID {itemId} is invalid.
'10009':
domain: API_BROWSE
category: REQUEST
description: The quantity value is invalid. The quantity must be greater than 0.
'10010':
domain: API_BROWSE
category: REQUEST
description: The item does not exist.
'10025':
domain: API_BROWSE
category: REQUEST
description: 'The header ''X-EBAY-C-MARKETPLACE-ID'' is required. The valid Marketplaces are: {supportedValues}.'
'403':
description: Insufficient permissions to fulfill the request
'409':
description: Conflict
x-response-codes:
errors:
'10011':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is already in the shopping cart. To change the quantity of the item, use the updateQuantity call.
'10016':
domain: API_BROWSE
category: BUSINESS
description: You have exceeded the maximum number of items in a cart, which is {MaxCartIems}. To add more items, either remove or purchase some of the items in the cart.
'10017':
domain: API_BROWSE
category: BUSINESS
description: The item does not meet the cart criteria and cannot be added to the cart.
'10018':
domain: API_BROWSE
category: BUSINESS
description: There is a limit on the quantity of this item that can be purchased. The quantity specified exceeds this limit.
'10019':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item you are trying to add to the cart.
'10021':
domain: API_BROWSE
category: BUSINESS
description: The item you are trying to add is not available in the quantity specified. Please adjust the quantity and try again.
'10022':
domain: API_BROWSE
category: BUSINESS
description: The item you are trying to add is not available for purchase. This can be for several reason such as, the listing has ended or the item is out of stock.
'10023':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item because the seller does not ship to the buyer's location.
'500':
description: Internal Server Error
x-response-codes:
errors:
'10000':
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/buy.shopping.cart
/shopping_cart/:
get:
tags:
- shopping_cart
description: '<span class="tablenote"><b>Note: </b><img src="/cms/img/docs/experimental-icon.svg" class="legend-icon experimental-icon" alt="Experimental Release" title="Experimental Release" /> This is an <a href="https://developer.ebay.com/api-docs/static/versioning.html#experimental">experimental</a> method that is available as a <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited" target="_blank"> <img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" title="Limited Release" alt="Limited Release" />(Limited Release)</a> to select developers approved by business units.</span> <p>This method retrieves all the items in the eBay member''s cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. There are no URI parameters or request payload. <br /><br />The response returns the summary details of all the items in the eBay member''s cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. If the cart is empty, the response is HTTP 204. </p> <br /><br /> The quantity and state of an item changes often. If the item becomes "unavailable" such as, when the listing has ended or the item is out of stock, the item will be returned in the <b> unavailableCartItems</b> container. <h3><b>URLs for this method</b></h3> <p><ul> <li><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/shopping_cart/</code></li> <li><b> Sandbox URL: </b><code>https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/</code> <br /><br /><b>Note: </b>This method is not available in the eBay API Explorer.</li> </ul> </p> <h3><b>Restrictions </b></h3> <p>This method can be used only for eBay members. For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p>'
operationId: getShoppingCart
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteShopcartResponse'
x-response-codes:
errors:
'10004':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is not available for purchase. This can be for several reason such as, the listing has ended or the item is out of stock.
'10005':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is revised.
'10006':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} in your cart is not available in the quantity specified. The quantity of this item has been changed to the quantity that is currently available. Please review this change before proceeding to checkout.
'10020':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item {itemId}.
'10024':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item {itemId} because the seller does not ship to the buyer's location.
'10025':
domain: API_BROWSE
category: REQUEST
description: 'The header ''X-EBAY-C-MARKETPLACE-ID'' is required. The valid Marketplaces are: {supportedValues}.'
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'10001':
domain: API_BROWSE
category: REQUEST
description: 'The X-EBAY-C-MARKETPLACE-ID value is not supported. The supported values are: {supportedValues}.'
'10002':
domain: API_BROWSE
category: REQUEST
description: Insufficient permissions to fulfill the request.
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'10000':
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/buy.shopping.cart
/shopping_cart/remove_item:
post:
tags:
- shopping_cart
description: '<span class="tablenote"><b>Note: </b><img src="/cms/img/docs/experimental-icon.svg" class="legend-icon experimental-icon" alt="Experimental Release" title="Experimental Release" /> This is an <a href="https://developer.ebay.com/api-docs/static/versioning.html#experimental">experimental</a> method that is available as a <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited" target="_blank"> <img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" title="Limited Release" alt="Limited Release" />(Limited Release)</a> to select developers approved by business units.</span> <p>This method removes a specific item from the eBay member''s cart. You specify the ID of the item in the cart (<b>cartItemId</b>) that you want to remove. <br /><br />The response returns all the items in the eBay member''s cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. If you remove the last item in the cart, the response is HTTP 204.<br /><br /> The quantity and state of an item changes often. If the item becomes "unavailable" such as, when the listing has ended or the item is out of stock, the item will be returned in the <b> unavailableCartItems</b> container.</p> <p span class="tablenote"><b>Note: </b> The <b> cartItemId</b> is not the same as the item ID. The <b> cartItemId</b> is the identifier of a specific item <i>in</i> the cart and is generated when the item was added to the cart.</span></p> <h3><b>URLs for this method</b></h3> <p><ul> <li><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/shopping_cart/remove_item</code></li> <li><b> Sandbox URL: </b><code>https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/remove_item</code> <br /><br /><b>Note: </b>This method is not available in the eBay API Explorer.</li> </ul> </p> <h3><b>Restrictions </b></h3> <p>This method can be used only for eBay members. For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p>'
operationId: removeItem
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveCartItemInput'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteShopcartResponse'
x-response-codes:
errors:
'10004':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is not available for purchase. This can be for several reason such as, the listing has ended or the item is out of stock.
'10005':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is revised.
'10006':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} in your cart is not available in the quantity specified. The quantity of this item has been changed to the quantity that is currently available. Please review this change before proceeding to checkout..
'10020':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item {itemId}.
'10024':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item {itemId} because the seller does not ship to the buyer's location.
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'10001':
domain: API_BROWSE
category: REQUEST
description: 'The X-EBAY-C-MARKETPLACE-ID value is not supported. The supported values are: {supportedValues}.'
'10002':
domain: API_BROWSE
category: REQUEST
description: Insufficient permissions to fulfill the request.
'10007':
domain: API_BROWSE
category: REQUEST
description: 'The field: {field} is required. Add the field and resubmit the call.'
'10012':
domain: API_BROWSE
category: REQUEST
description: The value of 'cartItemId' {cartItemId} is invalid.
'10025':
domain: API_BROWSE
category: REQUEST
description: 'The header ''X-EBAY-C-MARKETPLACE-ID'' is required. The valid Marketplaces are: {supportedValues}.'
'403':
description: Insufficient permissions to fulfill the request
'409':
description: Conflict
x-response-codes:
errors:
'10013':
domain: API_BROWSE
category: BUSINESS
description: The item is not in your cart.
'500':
description: Internal Server Error
x-response-codes:
errors:
'10000':
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/buy.shopping.cart
/shopping_cart/update_quantity:
post:
tags:
- shopping_cart
description: '<span class="tablenote"><b>Note: </b><img src="/cms/img/docs/experimental-icon.svg" class="legend-icon experimental-icon" alt="Experimental Release" title="Experimental Release" /> This is an <a href="https://developer.ebay.com/api-docs/static/versioning.html#experimental">experimental</a> method that is available as a <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited" target="_blank"> <img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" title="Limited Release" alt="Limited Release" />(Limited Release)</a> to select developers approved by business units.</span> <p>This method updates the quantity value of a specific item in the eBay member''s cart. You specify the ID of the item in the cart (<b>cartItemId</b>) and the new value for the quantity. If the <b> quantity</b> value is greater than the number of available, the <b> quantity</b> value is changed to the number available and a warning is returned. For example, if there are 15 baseballs available and you set the <b> quantity</b> value to 50, the service automatically changes the value of <b>quantity</b> to 15. <br /><br />The response returns all the items in the eBay member''s cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. The quantity and state of an item changes often. If the item becomes "unavailable" such as, the listing has ended or the item is out of stock, the item will be returned in the <b> unavailableCartItems</b> container.</p> <p span class="tablenote"><b>Note: </b> The <b> cartItemId</b> is not the same as the item ID. The <b> cartItemId</b> is the identifier of a specific item <i>in</i> the cart and is generated when the item was added to the cart.</span></p> <h3><b>URLs for this method</b></h3> <p><ul> <li><b> Production URL: </b> <code>https://api.ebay.com/buy/browse/v1/shopping_cart/update_quantity</code></li> <li><b> Sandbox URL: </b><code>https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/update_quantity</code> <br /><br /><b>Note: </b>This method is not available in the eBay API Explorer.</li> </ul> </p> <h3><b>Restrictions </b></h3> <p>This method can be used only for eBay members. For a list of supported sites and other restrictions, see <a href="/api-docs/buy/browse/overview.html#API">API Restrictions</a>.</p>'
operationId: updateQuantity
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCartItemInput'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteShopcartResponse'
x-response-codes:
errors:
'10004':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is not available for purchase. This can be for several reason such as, the listing has ended or the item is out of stock.
'10005':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} is revised.
'10006':
domain: API_BROWSE
category: BUSINESS
description: The item {itemId} in your cart is not available in the quantity specified. The quantity of this item has been changed to the quantity that is currently available. Please review this change before proceeding to checkout..
'10020':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item {itemId}.
'10024':
domain: API_BROWSE
category: BUSINESS
description: The buyer is blocked from purchasing the item {itemId} because the seller does not ship to the buyer's location.
'400':
description: Bad Request
x-response-codes:
errors:
'10001':
domain: API_BROWSE
category: REQUEST
description: 'The X-EBAY-C-MARKETPLACE-ID value is not supported. The supported values are: {supportedValues}.'
'10002':
domain: API_BROWSE
category: REQUEST
description: Insufficient permissions to fulfill the request.
'10007':
domain: API_BROWSE
category: REQUEST
description: 'The field: {field} is required. Add the field and resubmit the call.'
'10009':
domain: API_BROWSE
category: REQUEST
description: The quantity value is invalid. The quantity must be greater than 0.
'10012':
domain: API_BROWSE
category: REQUEST
description: The value of 'cartItemId' {cartItemId} is invalid.
'10025':
domain: API_BROWSE
category: REQUEST
description: 'The header ''X-EBAY-C-MARKETPLACE-ID'' is required. The valid Marketplaces are: {supportedValues}.'
'403':
description: Insufficient permissions to fulfill the request
'409':
description: Conflict
x-response-codes:
errors:
'10013':
domain: API_BROWSE
category: BUSINESS
description: The item is not in your cart.
'500':
description: Internal Server Error
x-response-codes:
errors:
'10000':
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/buy.shopping.cart
components:
schemas:
AddCartItemInput:
type: object
properties:
itemId:
type: string
description: 'The eBay RESTful identifier of the item you want added to the cart. <br /><br /> <b>RESTful Item ID Format: </b><code>v1</code>|<code><i>#</i></code>|<code><i>#</i></code> <br /><b> For example: </b> <br /><code>v1|2**********2|0</code> <br /><code>v1|1**********2|4**********2</code> <br /><br />For more information about item ID for RESTful APIs, see the <a href="/api-docs/buy/static/api-browse.html#Legacy">Legacy API compatibility</a> section of the <i>Buy APIs Overview</i>.<br /><br /><b> Maximum number of items in a cart: </b> 100'
quantity:
type: integer
description: 'The number of this item the buyer wants to purchase. If this value is greater than the number available, the service will change this value to the number available. If this happens, a warning is returned.<br /><br /><b> Maximum: </b> <i>number available</i>'
format: int32
description: The type that defines the fields for the <b>addItems</b> request.
AdditionalProductIdentity:
type: object
properties:
productIdentity:
type: array
description: An array of the product identifier/value pairs for the product associated with the item. This is returned if the seller has associated the eBay Product Identifier (ePID) with the item and the request has <b> fieldgroups</b> set to <code>PRODUCT</code>. <br /><br />The following table shows what is returned, based on the item information provided by the seller, when the <b> fieldgroups</b> set to <code>PRODUCT</code>. <br /><br /><div style="overflow-x:auto;"> <table border=1> <tr> <th> ePID Provided </th> <th> Product ID(s) Provided</th> <th> Response</th> </tr> <tr> <td> No </td> <td> No </td> <td> The <b> AdditionalProductIdentity</b> container is <i> not</i> returned.</td></tr> <tr> <td> No </td> <td> Yes </td> <td> The <b> AdditionalProductIdentity</b> container is <i> not</i> returned but the product identifiers specified by the seller are returned in the <b> localizedAspects</b> container. </td> </tr> <tr> <td> Yes </td> <td> No </td> <td> The <b> AdditionalProductIdentity</b> container is returned listing the product identifiers of the product.</td></tr> <tr> <td> Yes </td> <td> Yes </td> <td> The <b> AdditionalProductIdentity</b> container is returned listing all the product identifiers of the product and the product identifiers specified by the seller are returned in the <b> localizedAspects</b> container.</td> </tr> </table> </div>
items:
$ref: '#/components/schemas/ProductIdentity'
description: The type that defines the array of product identifiers associated with the item. This container is returned if the seller has associated the eBay Product Identifier (ePID) with the item and in the request <b> fieldgroups</b> is set to <code>PRODUCT</code>.
AddonService:
type: object
properties:
selection:
type: string
description: This field indicates whether the add-on service must be selected for the item. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:AddonServiceSelectionEnum'>eBay API documentation</a>
serviceFee:
description: The amount charged for the add-on service.
$ref: '#/components/schemas/ConvertedAmount'
serviceId:
type: string
description: The ID number of the add-on service.
serviceType:
type: string
description: The type of add-on service, such as AUTHENTICITY_GUARANTEE. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:AddonServiceTypeEnum'>eBay API documentation</a>
description: This container describes an add-on service that may be selected for an item or that may apply automatically. A charge may be associated with the add-on service.
Address:
type: object
properties:
addressLine1:
type: string
description: 'The first line of the street address. <b> Note: </b> This is conditionally returned in the <b> itemLocation</b> field.'
addressLine2:
type: string
description: The second line of the street address. This field is not always used, but can be used for 'Suite Number' or 'Apt Number'.
city:
type: string
description: The city of the address.
country:
type: string
description: The two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " target="_blank">ISO 3166</a> standard of the country of the address. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CountryCodeEnum'>eBay API documentation</a>
county:
type: string
description: The county of the address.
postalCode:
type: string
description: The postal code (or zip code in US) code of the address. Sellers set a postal code (or zip code in US) for items when they are listed. The postal code is used for calculating proximity searches. It is anonymized when returned in <b>itemLocation.postalCode</b> via the API.
stateOrProvince:
type: string
description: 'The state or province of the address. <b> Note: </b> This is conditionally returned in the <b> itemLocation</b> field.'
description: The type that defines the fields for an address.
Amount:
type: object
properties:
currency:
type: string
description: 'The list of valid currencies. Each <a href="https://www.iso.org/iso-4217-currency-codes.html " target="_blank">ISO 4217</a> currency code includes the currency name followed by the numeric value.<br /><br />For example, the Canadian Dollar code (CAD) would take the following form: <i>Canadian Dollar, 124</i>. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/ba:CurrencyCodeEnum''>eBay API documentation</a>'
value:
type: string
description: The value of the discounted amount.
Aspect:
type: object
properties:
localizedName:
type: string
description: The text representing the name of the aspect for the name/value pair, such as Brand.
localizedValues:
type: array
description: The text representing the value of the aspect for the name/value pair, such as Apple.
items:
type: string
description: 'The type that defines the fields for the name/value pairs for the aspects of the product. For example: BRAND/Apple'
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 (<b> refinementHref</b>) 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.
AspectGroup:
type: object
properties:
aspects:
type: array
description: 'An array of the name/value pairs for the aspects of the product. For example: BRAND/Apple'
items:
$ref: '#/components/schemas/Aspect'
localizedGroupName:
type: string
description: 'The name of a group of aspects. <br /><br />In the following example, <b> Product Identifiers</b> and <b> Process</b> are product aspect group names. Under the group name are the product aspect name/value pairs. <p><b> Product Identifiers</b> <br /> Brand/Apple <br /> Product Family/iMac</p> <p><b> Processor</b><br /> Processor Type/Intel <br /> Processor Speed/3.10</p> '
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 <b> fieldgroups</b> is set to <code>ASPECT_REFINEMENTS</code> or <code>FULL</code> in the request.
AttributeNameValue:
type: object
properties:
name:
type: string
description: The name of the product attribute, such as Make, Model, Year, etc.
value:
type: string
description: The value for the <b> name</b> attribute, such as BMW, R1200GS, 2011, etc.
description: The type the defines attribute name/value pair fields that specify a product. The type of data depends on the context. For example, if you were using this to specify a specific vehicle, the attribute names would be Make, Model, Year, etc.
AuthenticityGuaranteeProgram:
type: object
properties:
description:
type: string
description: An indication that the item is qualified for the Authenticity Guarantee program.
termsWebUrl:
type: string
description: The URL to the Authenticity Guarantee program terms of use.
description: A type that identifies whether the item is qualified for the Authenticity Guarantee program.
AuthenticityVerificationProgram:
type: object
properties:
description:
type: string
description: An indication that the item is from a verified seller.
termsWebUrl:
type: string
description: The URL to the Authenticity Verification program terms of use.
description: A type that identifies whether the item is from a verified seller.
AutoCorrections:
type: object
properties:
q:
type: string
description: The automatically spell-corrected keyword from the request.
AvailableCoupon:
type: object
properties:
constraint:
description: The limitations or restrictions of the coupon.
$ref: '#/components/schemas/CouponConstraint'
discountAmount:
description: The discount amount after the coupon is applied.
$ref: '#/components/schemas/Amount'
discountType:
type: string
description: The type of discount that the coupon applies. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:CouponDiscountType'>eBay API documentation</a>
message:
type: string
description: 'A description of the coupon.<br /><br /><span class="tablenote"><b> Note: </b> The value returned in the <b>termsWebUrl</b> field should appear for all experiences when displaying coupons. The value in the <b>availableCoupons.message</b> field must also be included, if returned in the API response.</span>'
redemptionCode:
type: string
description: The coupon code.
termsWebUrl:
type: string
description: 'The URL to the coupon terms of use.<br /><br /><span class="tablenote"><b> Note: </b> The value returned in the <b>termsWebUrl</b> field should appear for all experiences when displaying coupons. The value in the <b>availableCoupons.message</b> field must also be included, if returned in the API response.</span>'
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 <a href="/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.buyingOptions">buyingOptions</a>.
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 <b> fieldgroups</b> is set to <code>BUYING_OPTION_REFINEMENTS</code> or <code>FULL</code> in the request.
CartItem:
type: object
properties:
cartItemId:
type: string
description: The identifier for the item being added to the cart. This is generated when the item is added to the cart.
cartItemSubtotal:
description: This is the subtotal of cost of a specific item in the cart. This does not include taxes, shipping costs, discounts, etc. It is <b> price</b> * <b> quantity</b>.
$ref: '#/components/schemas/Amount'
image:
description: The primary image of the item. This is the image that appears on the eBay view item page for this item.
$ref: '#/components/schemas/Image'
itemId:
type: string
description: 'The RESTful identifier of the item. This identifier is generated when the item was listed. <br /><br /> <b>RESTful Item ID Format: </b><code>v1</code>|<code><i>#</i></code>|<code><i>#</i></code> <br /><b> For example: </b><br /> <code>v1|2**********2|0</code> <br /><code>v1|1**********2|4**********2</code>'
itemWebUrl:
type: string
description: The URL of the eBay view item page for the item.
price:
description: The cost of the item.
$ref: '#/components/schemas/Price'
quantity:
type: integer
description: The number of this item the buyer wants to purchase.
format: int32
title:
type: string
description: The title of the item. This can be written by the seller or come from the eBay product catalog.
description: The type that defines the fields for the individual items in a cart.
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 <b>categories</b> container in the response of the <b>search</b> method, and contains the name and ID of the item category.
CategoryDistribution:
type: object
properties:
categoryId:
type: string
description: The 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 <b> fieldgroups</b> is set to <code>CATEGORY_REFINEMENTS</code> or <code>FULL</code> in the request.
CommonDescriptions:
type: object
properties:
description:
type: string
description: The item description that is used by more than one of the item variations.
itemIds:
type: array
description: A list of item ids that have this description.
items:
type: string
description: The type that defines the fields for the item ids that all use a common description. Often the item variations within an item group all have the same description. Instead of repeating this description in the item details of each item, a description that is shared by at least one other item is returned in this container. If the description is unique, it is returned in the <b> items.description</b> field.
CompatibilityPayload:
type: object
properties:
compatibilityProperties:
type: array
description: 'An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be <br /><code>"name" : "Year", <br />"value" : "2019"</code> <p> For a list of the attributes required for cars and trucks and motorcycles see <a href="/api-docs/buy/static/api-browse.html#Check">Check compatibility</a> in the Buy Integration Guide.</p>'
items:
$ref: '#/components/schemas/AttributeNameValue'
description: 'An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be <br /><code>"name" : "Year", <br />"value" : "2019"</code> <p> For a list of the attributes required for cars and trucks and motorcycles see <a href="/api-docs/buy/static/api-browse.html#Check">Check compatibility</a> in the Buy Integration Guide.</p>'
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 <b> name</b> 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 <b>compatibility_filter</b> request field.
CompatibilityResponse:
type: object
properties:
compatibilityStatus:
type: string
description: 'An enumeration value that tells you if the item is compatible with the product. <br /><br />The values are: <ul> <li> <b> COMPATIBLE</b> - Indicates the item is compatible with the product specified in the request.</li> <li> <b> NOT_COMPATIBLE</b> - Indicates the item is not compatible with the product specified in the request. Be sure to check all the <b> value</b> fields to ensure they are correct as errors in the value can also cause this response.</li> <li> <b> UNDETERMINED</b> - Indicates one or more attributes for the specified product are missing so compatibility cannot be determined. The response returns the attributes that are missing.</li> </ul> Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityStatus''>eBay API documentation</a>'
warnings:
type: array
description: An array of warning messages. These types of errors do not prevent the method from executing but should be checked.
items:
$ref: '#/components/schemas/Error'
description: 'The type that defines the response fields for <b> checkCompatibility</b>. '
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, see <a href="https://developer.ebay.com/devzone/finding/callref/enums/conditionIdList.html " target="_blank">Item Condition IDs and Names</a>. <br /><br />Code so that your app gracefully handles any future changes to this list.
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 <b> fieldgroups</b> is set to <code>CONDITION_REFINEMENTS</code> or <code>FULL</code> in the request.
ConvertedAmount:
type: object
properties:
convertedFromCurrency:
type: string
description: The three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html " target="_blank">ISO 4217</a> code representing the currency of the amount in the <b> convertedFromValue</b> 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 <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CurrencyCodeEnum'>eBay API documentation</a>
convertedFromValue:
type: string
description: The monetary amount before any conversion is performed, in the currency specified by the <b> convertedFromCurrency</b> field. This value is required or returned only if currency conversion/localization is required. The <b> value</b> field contains the converted amount of this value, in the currency specified by the <b> currency</b> field.
currency:
type: string
description: The three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html " target="_blank">ISO 4217</a> code representing the currency of the amount in the <b> value</b> field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the <b> value</b> field. <br /><br /><b> Default:</b> The currency of the authenticated user's country. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CurrencyCodeEnum'>eBay API documentation</a>
value:
type: string
description: 'The monetary amount, in the currency specified by the <b> currency</b> field. If currency conversion/localization is required, this value is the converted amount, and the <b> convertedFromValue</b> 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.
CoreItem:
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 <b> image.imageUrl</b> 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, see <a href="https://pages.ebay.com/help/policies/adult-only.html " target="_blank">Adult items policy</a> for sellers and <a href="https://www.ebay.com/help/terms-conditions/default/searching-adult-items?id=4661 " target="_blank">Adult-Only items on eBay</a> for buyers.
ageGroup:
type: string
description: (Primary Item Aspect) The age group for which the product is recommended. For example, newborn, infant, toddler, kids, adult, etc. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
authenticityGuarantee:
description: 'A container for information about whether an item is qualified for the Authenticity Guarantee program.<br /><br />Under the Authenticity Guarantee program, the seller ships a purchased item to a a third-party authenticator who inspects the item and provides an authentication card for it before the item is shipped to the buyer. If the buyer returns the item, the authenticator first verifies that it is the same item in the same condition before returning it to the seller.<br /><br /><span class="tablenote"><b> Note: </b>Refer to the <a href="https://pages.ebay.com/authenticity-guarantee/ " target="_blank">Authenticity Guarantee</a> page for more information.</span>'
$ref: '#/components/schemas/AuthenticityGuaranteeProgram'
authenticityVerification:
description: A container for information about whether an item is from a verified seller.</span>
$ref: '#/components/schemas/AuthenticityVerificationProgram'
availableCoupons:
type: array
description: A list of available coupons for the item.
items:
$ref: '#/components/schemas/AvailableCoupon'
bidCount:
type: integer
description: This integer value indicates the total number of bids that have been placed against an auction item. This field is returned only for auction items.
format: int32
brand:
type: string
description: (Primary Item Aspect) The name brand of the item, such as Nike, Apple, etc. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
buyingOptions:
type: array
description: A comma separated list of all the purchase options available for the item. The values returned are:<ul><li><code>FIXED_PRICE</code> - Indicates the buyer can purchase the item for a set price using the Buy It Now button.</li><li><code>AUCTION</code> - 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.</li><li><code>BEST_OFFER</code> - Indicates the buyer can send the seller a price they're willing to pay for the item. The seller can accept, reject, or send a counter offer. For more information on how this works, see <a href="https://www.ebay.com/help/buying/buy-now/making-best-offer?id=4019 ">Making a Best Offer</a>.</li><li><code>CLASSIFIED_AD</code> - Indicates that the final sales transaction is to be completed outside of the eBay environment.</li></ul>Code so that your app gracefully handles any future changes to this list.
items:
type: string
categoryId:
type: string
description: The ID of the leaf category for this item. A leaf category is the lowest level in that category and has no children.
categoryPath:
type: string
description: 'Text that shows the category hierarchy of the item. For example: Computers/Tablets & Networking, Laptops & Netbooks, PC Laptops & Netbooks'
color:
type: string
description: (Primary Item Aspect) Text describing the color of the item. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
condition:
type: string
description: A short text description for the condition of the item, such as New or Used. For a list of condition names, see <a href="https://developer.ebay.com/devzone/finding/callref/enums/conditionIdList.html " target="_blank">Item Condition IDs and Names</a>. <br /><br />Code so that your app gracefully handles any future changes to this list.
conditionDescription:
type: string
description: A full text description for the condition of the item. This field elaborates on the value specified in the <b>condition</b> field and provides full details for the condition of the item.
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, see <a href="https://developer.ebay.com/devzone/finding/callref/enums/conditionIdList.html " target="_blank">Item Condition IDs and Names</a>. <br /><br />Code so that your app gracefully handles any future changes to this list.</span>
currentBidPrice:
description: The container that returns the current highest bid for an auction item. The value (string) field shows the dollar value of the current highest bid, and the currency (3-digit ISO code) field denotes the currency associated with that bid value. This container will only be returned for auction items.
$ref: '#/components/schemas/ConvertedAmount'
description:
type: string
description: The full description of the item that was created by the seller. This can be plain text or rich content and can be very large.
eligibleForInlineCheckout:
type: boolean
description: This field indicates if the item can be purchased using the Buy <a href="/api-docs/buy/order/resources/methods">Order API</a>. <ul> <li>If the value of this field is <code>true</code>, this indicates that the item can be purchased using the <b> Order API</b>. </li> <li>If the value of this field is <code>false</code>, this indicates that the item cannot be purchased using the <b> Order API</b> and must be purchased on the eBay site.</li> </ul>
enabledForGuestCheckout:
type: boolean
description: This indicates if the item can be purchased using Guest Checkout in the <a href="/api-docs/buy/order/resources/methods">Order API</a>. You can use this flag to exclude items from your inventory that are not eligible for Guest Checkout, such as gift cards.
energyEfficiencyClass:
type: string
description: This indicates the <a href="https://en.wikipedia.org/wiki/European_Union_energy_label ">European energy efficiency</a> rating (EEK) of the item. This field is returned only if the seller specified the energy efficiency rating. <br /><br />The rating is a set of energy efficiency classes from A to G, where 'A' is the most energy efficient and 'G' is the least efficient. This rating helps buyers choose between various models. <br /><br />When the manufacturer's specifications for this item are available, the link to this information is returned in the <b> productFicheWebUrl</b> field.
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.
estimatedAvailabilities:
type: array
description: The estimated number of this item that are available for purchase. Because the quantity of an item can change several times within a second, it is impossible to return the exact quantity. So instead of returning quantity, the estimated availability of the item is returned.
items:
$ref: '#/components/schemas/EstimatedAvailability'
gender:
type: string
description: '(Primary Item Aspect) The gender for the item. This is used for items that could vary by gender, such as clothing. For example: male, female, or unisex. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.'
gtin:
type: string
description: The unique Global Trade Item number of the item as defined by <a href="https://www.gtin.info " target="_blank">https://www.gtin.info</a>. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.
image:
description: The URL of the primary image of the item. The other images of the item are returned in the <b> additionalImages</b> container.
$ref: '#/components/schemas/Image'
inferredEpid:
type: string
description: 'The ePID (eBay Product ID of a product from the eBay product catalog) for the item, which has been programmatically determined by eBay using the item''s title, aspects, and other data. <br /><br />If the seller provided an ePID for the item, the seller''s value is returned in the <b> epid</b> field. <br /><br /><span class="tablenote"><b> Note: </b> This field is returned only for authorized Partners.</span>'
itemAffiliateWebUrl:
type: string
description: 'The URL of the View Item page of the item, which includes the affiliate tracking ID. This field is only returned if the eBay partner enables affiliate tracking for the item by including the <a href="/api-docs/buy/static/api-browse.html#Headers"><code>X-EBAY-C-ENDUSERCTX</code></a> request header in the method. <br /> <br /><span class="tablenote"><b>Note: </b> eBay Partner Network, in order to be commissioned for your sales, you must use this URL to forward your buyer to the ebay.com site. </span>'
itemCreationDate:
type: string
description: A timestamp that indicates the date and time an item listing was created.<br /><br />This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which can be converted into the local time of the buyer.
itemEndDate:
type: string
description: 'This timestamp indicates 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.<br /><br /><span class="tablenote"><b> Note: </b>This field is only returned for auction listings.</span>'
itemId:
type: string
description: The unique RESTful identifier of the item.
itemLocation:
description: The physical location of the item.
$ref: '#/components/schemas/Address'
itemWebUrl:
type: string
description: The URL of the View Item page of the item. This enables you to include a "Report Item on eBay" link that takes the buyer to the View Item page on eBay. From there they can report any issues regarding this item to eBay.
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.
localizedAspects:
type: array
description: An array of containers that show the complete list of the aspect name/value pairs that describe the variation of the item.
items:
$ref: '#/components/schemas/TypedNameValue'
lotSize:
type: integer
description: 'The number of items in a lot. In other words, a lot size is the number of items that are being sold together. <br /><br />A lot is a set of two or more items included in a single listing that must be purchased together in a single order line item. All the items in the lot are the same but there can be multiple items in a single lot, such as the package of batteries shown in the example below. <br /><br /><table border="1"> <tr> <tr> <th>Item</th> <th>Lot Definition</th> <th>Lot Size</th></tr> <tr> <td>A package of 24 AA batteries</td> <td>A box of 10 packages</td> <td>10 </td> </tr> <tr> <td>A P235/75-15 Goodyear tire </td> <td>4 tires </td> <td>4 </td> </tr> <tr> <td>Fashion Jewelry Rings </td> <td>Package of 100 assorted rings </td> <td>100 </td> </tr></table> <br /><br /><span class="tablenote"><b>Note: </b> Lots are not supported in all categories. </span>'
format: int32
marketingPrice:
description: The original price and the discount amount and percentage.
$ref: '#/components/schemas/MarketingPrice'
material:
type: string
description: (Primary Item Aspect) Text describing what the item is made of. For example, silk. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
minimumPriceToBid:
description: The minimum price of the next bid, which means to place a bid it must be equal to or greater than this amount. If the auction hasn't received any bids, the minimum bid price is the same as the starting bid. Otherwise, the minimum bid price is equal to the current bid plus the bid increment. For details about bid increments, see <a href="https://www.ebay.com/help/buying/bidding/automatic-bidding?id=4014 ">Automatic bidding</a>.
$ref: '#/components/schemas/ConvertedAmount'
mpn:
type: string
description: The manufacturer's part number, which is a unique number that identifies a specific product. To identify the product, this is always used along with brand.
pattern:
type: string
description: (Primary Item Aspect) Text describing the pattern used on the item. For example, paisley. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
paymentMethods:
type: array
description: The payment methods for the item, including the payment method types, brands, and instructions for the buyer.
items:
$ref: '#/components/schemas/PaymentMethod'
price:
description: 'The cost of just the item. This amount does not include any adjustments such as discounts or shipping costs.<br /><br /><span class="tablenote"><b> Note: </b>The price does include the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the <a href="/api-docs/static/rest-request-components.html#HTTP"><code>X-EBAY-C-MARKETPLACE-ID</code></a> request header specifying the supported marketplace (such as <code>EBAY_GB</code>) to see the VAT-inclusive pricing. For more information on VAT, refer to <a href="https://www.ebay.co.uk/help/listings/default/vat-obligations-eu?id=4650&st=12&pos=1&query=Your%20VAT%20obligations%20in%20the%20EU&intent=VAT">VAT Obligations in the EU</a>.</span>'
$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 <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:PriceDisplayConditionEnum'>eBay API documentation</a>
primaryItemGroup:
description: 'The container that returns details of a primary item group (parent ID of an item group). An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. <br /><br />When an item group is created, one of the item variations, such as the red shirt size L, is chosen as the "parent". All the other items in the group are the children, such as the blue shirt size L, red shirt size M, etc.<br /><br /><span class="tablenote"><b> Note: </b> This container is returned if the <b> item_id</b> in the request is for an item group (items with variations, such as color and size). This container is also returned on a request for <b> item_group_ids</b>.</span>'
$ref: '#/components/schemas/ItemGroupSummary'
primaryProductReviewRating:
description: The container that returns the product rating details, such as review count, rating histogram, and average rating.
$ref: '#/components/schemas/ReviewRating'
priorityListing:
type: boolean
description: This field is returned as <code>true</code> 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.<br /><br />For more information, see <a href="https://pages.ebay.com/seller-center/listing-and-marketing/promoted-listings.html " target="_blank">Promoted Listings</a>.
product:
description: The container that returns the product information of the item.
$ref: '#/components/schemas/Product'
productFicheWebUrl:
type: string
description: The URL of a page containing the manufacturer's specification of this item, which helps buyers make a purchasing decision. This information is available only for items that include the European energy efficiency rating (EEK) but is not available for <em> all</em> items with an EEK rating and is returned only if this information is available. The EEK rating of the item is returned in the <b> energyEfficiencyClass</b> field.
qualifiedPrograms:
type: array
description: 'An array of the qualified programs available for the item, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION.<br /><br />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.<br /><br /><span class="tablenote"><b>Note: </b> eBay Plus is available only to buyers in Germany, Austria, and Australia marketplaces.</span><br /><br />The eBay <a href="https://pages.ebay.com/authenticity-guarantee/ " target="_blank">Authenticity Guarantee</a> program enables third-party authenticators to perform authentication verification inspections on items such as watches and sneakers.'
items:
type: string
quantityLimitPerBuyer:
type: integer
description: The maximum number for a specific item that one buyer can purchase.
format: int32
reservePriceMet:
type: boolean
description: 'This indicates if the reserve price of the item has been met. A reserve price is set by the seller and is the minimum amount the seller is willing to sell the item for. <p>If the highest bid is not equal to or higher than the reserve price when the auction ends, the listing ends and the item is not sold.</p> <p><b> Note: </b>This is returned only for auctions that have a reserve price.</p>'
returnTerms:
description: The container that returns an overview of the seller's return policy.
$ref: '#/components/schemas/ItemReturnTerms'
seller:
description: The container that returns basic and detailed about the seller of the item, such as name, feedback score, and contact information.
$ref: '#/components/schemas/SellerDetail'
sellerItemRevision:
type: string
description: 'An identifier generated/incremented when a seller revises the item. There are two types of item revisions: <ul><li>Seller changes, such as changing the title</li> <li>eBay system changes, such as changing the quantity when an item is purchased</li></ul> This ID is changed <em> only</em> when the seller makes a change to the item. This means you cannot use this value to determine if the quantity has changed.'
shippingOptions:
type: array
description: 'An array of shipping options containers that have the details about cost, carrier, etc. of one shipping option. '
items:
$ref: '#/components/schemas/ShippingOption'
shipToLocations:
description: The container that returns the geographic regions to be included and excluded that define where the item can be shipped.
$ref: '#/components/schemas/ShipToLocations'
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.).
size:
type: string
description: (Primary Item Aspect) The size of the item. For example, '7' for a size 7 shoe. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
sizeSystem:
type: string
description: '(Primary Item Aspect) The sizing system of the country. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container. <br /><br /><b> Valid Values: </b> <br />AU (Australia), <br />BR (Brazil), <br />CN (China), <br />DE (Germany), <br />EU (European Union), <br /> FR (France), <br /> IT (Italy), <br />JP (Japan), <br />MX (Mexico), <br />US (USA), <br /> UK (United Kingdom) <br /><br />Code so that your app gracefully handles any future changes to this list. '
sizeType:
type: string
description: (Primary Item Aspect) Text describing a size group in which the item would be included, such as regular, petite, plus, big-and-tall or maternity. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
subtitle:
type: string
description: A subtitle is optional and allows the seller to provide more information about the product, possibly including keywords that may assist with search results.
taxes:
type: array
description: The container for the tax information for the item.
items:
$ref: '#/components/schemas/Taxes'
title:
type: string
description: 'The seller-created title of the item. <br><br><b> Maximum Length: </b> 80 characters'
topRatedBuyingExperience:
type: boolean
description: 'This indicates if the item 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 items in 1 business day with tracking provided, and the added comfort of knowing this item is from experienced sellers with the highest buyer ratings. See the <a href="https://pages.ebay.com/topratedplus/index.html " target="_blank">Top Rated Plus Items </a> and <a href="https://pages.ebay.com/help/sell/top-rated.html " target="_blank">Becoming a Top Rated Seller and qualifying for Top Rated Plus</a> help topics for more information.'
tyreLabelImageUrl:
type: string
description: The URL to the image that shows the information on the tyre label.
uniqueBidderCount:
type: integer
description: This integer value indicates the number of different eBay users who have placed one or more bids on an auction item. This field is only applicable to auction items.
format: int32
unitPrice:
description: 'This is 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. <br /><br />For example: <br /><br /><code>"unitPricingMeasure": "100g",<br /> "unitPrice": {<br /> "value": "7.99",<br /> "currency": "GBP"</code>'
$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. <br /><br />For example, the following tells the buyer that the item is 7.99 per 100 grams. <br /><br /><code>"unitPricingMeasure": "100g",<br /> "unitPrice": {<br /> "value": "7.99",<br /> "currency": "GBP"</code>'
description: An array of containers with the details for all of the items returned.
CouponConstraint:
type: object
properties:
expirationDate:
type: string
description: This timestamp provides the expiration date of the coded coupon.
description: This type is used to provide the expiration date of a coded coupon.
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.
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 <b> name</b> field.
description: An array of name/value pairs that provide details regarding the error.
EstimatedAvailability:
type: object
properties:
availabilityThreshold:
type: integer
description: This field is return only when the seller sets their '<a href="#display-item-quantity">display item quantity</a>' preference to <b> Display "More than 10 available" in your listing (if applicable)</b>. The value of this field will be "10", which is the threshold value. <br /><br />Code so that your app gracefully handles any future changes to this value.
format: int32
availabilityThresholdType:
type: string
description: '<a name="display-item-quantity"></a> This field is return only when the seller sets their <b> Display Item Quantity</b> preference to <b> Display "More than 10 available" in your listing (if applicable)</b>. The value of this field will be <code> MORE_THAN</code>. This indicates that the seller has more than the ''quantity display preference'', which is 10, in stock for this item. <br /><br /> The following are the display item quantity preferences the seller can set. <br /><ul><li> <b> Display "More than 10 available" in your listing (if applicable) </b><ul> <li>If the seller enables this preference, this field is returned as long as there are more than 10 of this item in inventory.</li> <li> If the quantity is equal to 10 or drops below 10, this field is not returned and the estimated quantity of the item is returned in the <b> estimatedAvailableQuantity</b> field.</li></ul> </li> <li> <b> Display the exact quantity in your items</b> <br />If the seller enables this preference, the <b> availabilityThresholdType</b> and <b> availabilityThreshold</b> fields are not returned and the estimated quantity of the item is returned in the <b> estimatedAvailableQuantity</b> field.<br /><br /><b> Note: </b> Because the quantity of an item can change several times within a second, it is impossible to return the exact quantity. </li></ul> <br />Code so that your app gracefully handles any future changes to these preferences. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:AvailabilityThresholdEnum''>eBay API documentation</a>'
deliveryOptions:
type: array
description: 'An array of available delivery options. <br><br><b> Valid Values: </b> SHIP_TO_HOME, SELLER_ARRANGED_LOCAL_PICKUP, IN_STORE_PICKUP, PICKUP_DROP_OFF, or DIGITAL_DELIVERY <br /><br />Code so that your app gracefully handles any future changes to this list. '
items:
type: string
description: ' For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:DeliveryOptionsEnum''>eBay API documentation</a>'
estimatedAvailabilityStatus:
type: string
description: 'An enumeration value representing the inventory status of this item.<br /><br /><span class="tablenote"><b> Note: </b>Be sure to review the <b>itemEndDate</b> field to determine whether the item is available for purchase.</span><br><br><b> Valid Values: </b> IN_STOCK, LIMITED_STOCK, or OUT_OF_STOCK <br /><br />Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:AvailabilityStatusEnum''>eBay API documentation</a>'
estimatedAvailableQuantity:
type: integer
description: The estimated number of this item that are available for purchase. Because the quantity of an item can change several times within a second, it is impossible to return the exact quantity. So instead of returning quantity, the estimated availability of the item is returned.
format: int32
estimatedSoldQuantity:
type: integer
description: The estimated number of this item that have been sold.
format: int32
description: The type that defines the fields for the estimated item availability information.
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 the defines the details of an image, such as size and image URL. Currently, only <b> imageUrl</b> is populated. The <b> height</b> and <b> width</b> were added for future use.
Item:
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 <b> image.imageUrl</b> field.
items:
$ref: '#/components/schemas/Image'
addonServices:
type: array
description: A list of add-on services that may be selected for the item or that may apply automatically.
items:
$ref: '#/components/schemas/AddonService'
adultOnly:
type: boolean
description: This indicates if the item is for adults only. For more information about adult-only items on eBay, see <a href="https://pages.ebay.com/help/policies/adult-only.html " target="_blank">Adult items policy</a> for sellers and <a href="https://www.ebay.com/help/terms-conditions/default/searching-adult-items?id=4661" target="_blank">Adult-Only items on eBay</a> for buyers.
ageGroup:
type: string
description: (Primary Item Aspect) The age group for which the product is recommended. For example, newborn, infant, toddler, kids, adult, etc. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
authenticityGuarantee:
description: 'A container for information about whether an item, or the item group when returned for the <b>getItemsByItemGroup</b> method, is qualified for the Authenticity Guarantee program.<br /><br /><span class="tablenote"><b>Note: </b>The <code>AUTHENTICITY_GUARANTEE</code> value being returned by the <b>getItemsByItemGroup</b> method indicates that at least one item in the item group supports this program, but doesn''t guarantee that the program is available to all items in the item group. To verify if the Authenticity Program is indeed available for the item that you are interested in, grab the <b>items.itemId</b> value for that item and use the <b>getItem</b> method. This method will return specific details on that particular item, including whether or not the Authenticity Guarantee Program is available for the item. Look for the <b>qualifiedPrograms</b> array and <b>authenticityGuarantee</b> container in the <b>getItem</b> response for this information.</span><br /><br />Under the Authenticity Guarantee program, the seller ships a purchased item to a a third-party authenticator who inspects the item and provides an authentication card for it before the item is shipped to the buyer. If the buyer returns the item, the authenticator first verifies that it is the same item in the same condition before returning it to the seller.<br /><br /><span class="tablenote"><b> Note: </b>Refer to the <a href="https://pages.ebay.com/authenticity-guarantee/ " target="_blank">Authenticity Guarantee</a> page for more information.</span>'
$ref: '#/components/schemas/AuthenticityGuaranteeProgram'
authenticityVerification:
description: A container for information about whether an item is from a verified seller.</span>
$ref: '#/components/schemas/AuthenticityVerificationProgram'
availableCoupons:
type: array
description: A list of available coupons for the item.
items:
$ref: '#/components/schemas/AvailableCoupon'
bidCount:
type: integer
description: This integer value indicates the total number of bids that have been placed against an auction item. This field is returned only for auction items.
format: int32
brand:
type: string
description: (Primary Item Aspect) The name brand of the item, such as Nike, Apple, etc. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
buyingOptions:
type: array
description: A comma separated list of all the purchase options available for the item. The values returned are:<ul><li><code>FIXED_PRICE</code> - Indicates the buyer can purchase the item for a set price using the Buy It Now button.</li><li><code>AUCTION</code> - 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.</li><li><code>BEST_OFFER</code> - Indicates the buyer can send the seller a price they're willing to pay for the item. The seller can accept, reject, or send a counter offer. For more information on how this works, see <a href="https://www.ebay.com/help/buying/buy-now/making-best-offer?id=4019 ">Making a Best Offer</a>.</li><li><code>CLASSIFIED_AD</code> - Indicates that the final sales transaction is to be completed outside of the eBay environment.</li></ul>Code so that your app gracefully handles any future changes to this list.
items:
type: string
categoryId:
type: string
description: The ID of the leaf category for this item. A leaf category is the lowest level in that category and has no children.
categoryIdPath:
type: string
description: 'The IDs of every category in the item path, separated by pipe characters, starting with the top level parent category.<br /><br />For example, if an item belongs to the top level category Home and Garden (category ID 11700), followed by Home Improvement (159907), Heating, Cooling and Air (69197), and Thermostats (115947), the field would return the value: <code>11700|159907|69197|115947</code>.'
categoryPath:
type: string
description: 'Text that shows the category hierarchy of the item. For example: Computers/Tablets & Networking, Laptops & Netbooks, PC Laptops & Netbooks'
color:
type: string
description: (Primary Item Aspect) Text describing the color of the item. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
condition:
type: string
description: A short text description for the condition of the item, such as New or Used. For a list of condition names, see <a href="https://developer.ebay.com/devzone/finding/callref/enums/conditionIdList.html " target="_blank">Item Condition IDs and Names</a>. <br /><br />Code so that your app gracefully handles any future changes to this list.
conditionDescription:
type: string
description: A full text description for the condition of the item. This field elaborates on the value specified in the <b>condition</b> field and provides full details for the condition of the item.
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, see <a href="https://developer.ebay.com/devzone/finding/callref/enums/conditionIdList.html " target="_blank">Item Condition IDs and Names</a>. <br /><br />Code so that your app gracefully handles any future changes to this list.
currentBidPrice:
description: The container that returns the current highest bid for an auction item. The value (string) field shows the dollar value of the current highest bid, and the currency (3-digit ISO code) field denotes the currency associated with that bid value. This container will only be returned for auction items.
$ref: '#/components/schemas/ConvertedAmount'
description:
type: string
description: The full description of the item that was created by the seller. This can be plain text or rich content and can be very large.
ecoParticipationFee:
description: The Eco Participation fee, a fee paid by the buyer that is applied to the cost of the eventual disposal of the purchased item. The fee is remitted in full to the eco organization.<br /><br />Currently, this value is required for electronic devices and furniture.
$ref: '#/components/schemas/ConvertedAmount'
eligibleForInlineCheckout:
type: boolean
description: This field indicates if the item can be purchased using the Buy <a href="/api-docs/buy/order/resources/methods">Order API</a>. <ul> <li>If the value of this field is <code>true</code>, this indicates that the item can be purchased using the <b> Order API</b>. </li> <li>If the value of this field is <code>false</code>, this indicates that the item cannot be purchased using the <b> Order API</b> and must be purchased on the eBay site.</li> </ul>
enabledForGuestCheckout:
type: boolean
description: This indicates if the item can be purchased using Guest Checkout in the <a href="/api-docs/buy/order/resources/methods">Order API</a>. You can use this flag to exclude items from your inventory that are not eligible for Guest Checkout, such as gift cards.
energyEfficiencyClass:
type: string
description: This indicates the <a href="https://en.wikipedia.org/wiki/European_Union_energy_label ">European energy efficiency</a> rating (EEK) of the item. This field is returned only if the seller specified the energy efficiency rating. <br /><br />The rating is a set of energy efficiency classes from A to G, where 'A' is the most energy efficient and 'G' is the least efficient. This rating helps buyers choose between various models. <br /><br />When the manufacturer's specifications for this item are available, the link to this information is returned in the <b> productFicheWebUrl</b> field.
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.
estimatedAvailabilities:
type: array
description: The estimated number of this item that are available for purchase. Because the quantity of an item can change several times within a second, it is impossible to return the exact quantity. So instead of returning quantity, the estimated availability of the item is returned.
items:
$ref: '#/components/schemas/EstimatedAvailability'
gender:
type: string
description: '(Primary Item Aspect) The gender for the item. This is used for items that could vary by gender, such as clothing. For example: male, female, or unisex. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.'
gtin:
type: string
description: The unique Global Trade Item number of the item as defined by <a href="https://www.gtin.info " target="_blank">https://www.gtin.info</a>. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.
image:
description: The URL of the primary image of the item. The other images of the item are returned in the <b> additionalImages</b> container.
$ref: '#/components/schemas/Image'
inferredEpid:
type: string
description: 'The ePID (eBay Product ID of a product from the eBay product catalog) for the item, which has been programmatically determined by eBay using the item''s title, aspects, and other data. <br /><br />If the seller provided an ePID for the item, the seller''s value is returned in the <b> epid</b> field. <br /><br /><span class="tablenote"><b> Note: </b> This field is returned only for authorized Partners.</span>'
itemAffiliateWebUrl:
type: string
description: 'The URL of the View Item page of the item, which includes the affiliate tracking ID. This field is only returned if the eBay partner enables affiliate tracking for the item by including the <a href="/api-docs/buy/static/api-browse.html#Headers"><code>X-EBAY-C-ENDUSERCTX</code></a> request header in the method. <br /> <br /><span class="tablenote"><b>Note: </b> eBay Partner Network, in order to be commissioned for your sales, you must use this URL to forward your buyer to the ebay.com site. </span>'
itemCreationDate:
type: string
description: A timestamp that indicates the date and time an item listing was created.<br /><br />This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which can be converted into the local time of the buyer.
itemEndDate:
type: string
description: 'This timestamp indicates 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.<br /><br /><span class="tablenote"><b> Note: </b>This field is only returned for auction listings.</span>'
itemId:
type: string
description: The unique RESTful identifier of the item.
itemLocation:
description: The physical location of the item.
$ref: '#/components/schemas/Address'
itemWebUrl:
type: string
description: The URL of the View Item page of the item. This enables you to include a "Report Item on eBay" link that takes the buyer to the View Item page on eBay. From there they can report any issues regarding this item to eBay.
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 where the item is listed. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:MarketplaceIdEnum'>eBay API documentation</a>
localizedAspects:
type: array
description: An array of containers that show the complete list of the aspect name/value pairs that describe the variation of the item.
items:
$ref: '#/components/schemas/TypedNameValue'
lotSize:
type: integer
description: 'The number of items in a lot. In other words, a lot size is the number of items that are being sold together. <br /><br />A lot is a set of two or more items included in a single listing that must be purchased together in a single order line item. All the items in the lot are the same but there can be multiple items in a single lot, such as the package of batteries shown in the example below. <br /><br /><table border="1"> <tr> <tr> <th>Item</th> <th>Lot Definition</th> <th>Lot Size</th></tr> <tr> <td>A package of 24 AA batteries</td> <td>A box of 10 packages</td> <td>10 </td> </tr> <tr> <td>A P235/75-15 Goodyear tire </td> <td>4 tires </td> <td>4 </td> </tr> <tr> <td>Fashion Jewelry Rings </td> <td>Package of 100 assorted rings </td> <td>100 </td> </tr></table> <br /><br /><span class="tablenote"><b>Note: </b> Lots are not supported in all categories. </span>'
format: int32
marketingPrice:
description: The original price and the discount amount and percentage.
$ref: '#/components/schemas/MarketingPrice'
material:
type: string
description: (Primary Item Aspect) Text describing what the item is made of. For example, silk. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
minimumPriceToBid:
description: The minimum price of the next bid, which means to place a bid it must be equal to or greater than this amount. If the auction hasn't received any bids, the minimum bid price is the same as the starting bid. Otherwise, the minimum bid price is equal to the current bid plus the bid increment. For details about bid increments, see <a href="https://www.ebay.com/help/buying/bidding/automatic-bidding?id=4014 ">Automatic bidding</a>.
$ref: '#/components/schemas/ConvertedAmount'
mpn:
type: string
description: The manufacturer's part number, which is a unique number that identifies a specific product. To identify the product, this is always used along with brand.
pattern:
type: string
description: (Primary Item Aspect) Text describing the pattern used on the item. For example, paisley. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
paymentMethods:
type: array
description: The payment methods for the item, including the payment method types, brands, and instructions for the buyer.
items:
$ref: '#/components/schemas/PaymentMethod'
price:
description: 'The cost of just the item. This amount does not include any adjustments such as discounts or shipping costs.<br /><br /><span class="tablenote"><b> Note: </b>The price does include the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the <a href="/api-docs/static/rest-request-components.html#HTTP"><code>X-EBAY-C-MARKETPLACE-ID</code></a> request header specifying the supported marketplace (such as <code>EBAY_GB</code>) to see the VAT-inclusive pricing. For more information on VAT, refer to <a href="https://www.ebay.co.uk/help/listings/default/vat-obligations-eu?id=4650&st=12&pos=1&query=Your%20VAT%20obligations%20in%20the%20EU&intent=VAT">VAT Obligations in the EU</a>.</span>'
$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 <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:PriceDisplayConditionEnum'>eBay API documentation</a>
primaryItemGroup:
description: 'The container that returns details of a primary item group (parent ID of an item group). An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. <br /><br />When an item group is created, one of the item variations, such as the red shirt size L, is chosen as the "parent". All the other items in the group are the children, such as the blue shirt size L, red shirt size M, etc.<br /><br /><span class="tablenote"><b> Note: </b> This container is returned only if the <b> item_id</b> in the request is for an item group (items with variations, such as color and size).</span>'
$ref: '#/components/schemas/ItemGroupSummary'
primaryProductReviewRating:
description: The container that returns the product rating details, such as review count, rating histogram, and average rating.
$ref: '#/components/schemas/ReviewRating'
priorityListing:
type: boolean
description: This field is returned as <code>true</code> 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.<br /><br />For more information, see <a href="https://pages.ebay.com/seller-center/listing-and-marketing/promoted-listings.html " target="_blank">Promoted Listings</a>.
product:
description: The container that returns the product information of the item.
$ref: '#/components/schemas/Product'
productFicheWebUrl:
type: string
description: The URL of a page containing the manufacturer's specification of this item, which helps buyers make a purchasing decision. This information is available only for items that include the European energy efficiency rating (EEK) but is not available for <em> all</em> items with an EEK rating and is returned only if this information is available. The EEK rating of the item is returned in the <b> energyEfficiencyClass</b> field.
qualifiedPrograms:
type: array
description: 'An array of the qualified programs available for the item, or for the item group when returned for the <b>getItemsByItemGroup</b> method, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION.<br /><br /><span class="tablenote"><b>Note: </b>The <code>AUTHENTICITY_GUARANTEE</code> value being returned by the <b>getItemsByItemGroup</b> method indicates that at least one item in the item group supports this program, but doesn''t guarantee that the program is available to all items in the item group. To verify if the Authenticity Program is indeed available for the item that you are interested in, grab the <b>items.itemId</b> value for that item and use the <b>getItem</b> method. This method will return specific details on that particular item, including whether or not the Authenticity Guarantee Program is available for the item. Look for the <b>qualifiedPrograms</b> array and <b>authenticityGuarantee</b> container in the <b>getItem</b> response for this information.</span><br /><br />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.<br /><br /><span class="tablenote"><b>Note: </b> eBay Plus is available only to buyers in Germany, Austria, and Australia marketplaces.</span><br /><br />The eBay <a href="https://pages.ebay.com/authenticity-guarantee/ " target="_blank">Authenticity Guarantee</a> program enables third-party authenticators to perform authentication verification inspections on items such as watches and sneakers.'
items:
type: string
quantityLimitPerBuyer:
type: integer
description: The maximum number for a specific item that one buyer can purchase.
format: int32
reservePriceMet:
type: boolean
description: 'This indicates if the reserve price of the item has been met. A reserve price is set by the seller and is the minimum amount the seller is willing to sell the item for. <p>If the highest bid is not equal to or higher than the reserve price when the auction ends, the listing ends and the item is not sold.</p> <p><b> Note: </b>This is returned only for auctions that have a reserve price.</p>'
returnTerms:
description: The container that returns an overview of the seller's return policy.
$ref: '#/components/schemas/ItemReturnTerms'
seller:
description: The container that returns basic and detailed about the seller of the item, such as name, feedback score, and contact information.
$ref: '#/components/schemas/SellerDetail'
sellerCustomPolicies:
type: array
description: A list of the custom policies that are applied to a listing.
items:
$ref: '#/components/schemas/SellerCustomPolicy'
sellerItemRevision:
type: string
description: 'An identifier generated/incremented when a seller revises the item. There are two types of item revisions: <ul><li>Seller changes, such as changing the title</li> <li>eBay system changes, such as changing the quantity when an item is purchased</li></ul> This ID is changed <em> only</em> when the seller makes a change to the item. This means you cannot use this value to determine if the quantity has changed.'
shippingOptions:
type: array
description: 'An array of shipping options containers that have the details about cost, carrier, etc. of one shipping option. '
items:
$ref: '#/components/schemas/ShippingOption'
shipToLocations:
description: The container that returns the geographic regions to be included and excluded that define where the item can be shipped.
$ref: '#/components/schemas/ShipToLocations'
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.).
size:
type: string
description: (Primary Item Aspect) The size of the item. For example, '7' for a size 7 shoe. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
sizeSystem:
type: string
description: '(Primary Item Aspect) The sizing system of the country. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container. <br /><br /><b> Valid Values: </b> <br />AU (Australia), <br />BR (Brazil), <br />CN (China), <br />DE (Germany), <br />EU (European Union), <br /> FR (France), <br /> IT (Italy), <br />JP (Japan), <br />MX (Mexico), <br />US (USA), <br /> UK (United Kingdom) <br /><br />Code so that your app gracefully handles any future changes to this list. '
sizeType:
type: string
description: (Primary Item Aspect) Text describing a size group in which the item would be included, such as regular, petite, plus, big-and-tall or maternity. All the item aspects, including this aspect, are returned in the <b> localizedAspects</b> container.
subtitle:
type: string
description: A subtitle is optional and allows the seller to provide more information about the product, possibly including keywords that may assist with search results.
taxes:
type: array
description: The container for the tax information for the item.
items:
$ref: '#/components/schemas/Taxes'
title:
type: string
description: 'The seller-created title of the item. <br><br><b> Maximum Length: </b> 80 characters'
topRatedBuyingExperience:
type: boolean
description: 'This indicates if the item 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 items in 1 business day with tracking provided, and the added comfort of knowing this item is from experienced sellers with the highest buyer ratings. See the <a href="https://pages.ebay.com/topratedplus/index.html " target="_blank">Top Rated Plus Items </a> and <a href="https://pages.ebay.com/help/sell/top-rated.html " target="_blank">Becoming a Top Rated Seller and qualifying for Top Rated Plus</a> help topics for more information.'
tyreLabelImageUrl:
type: string
description: The URL to the image that shows the information on the tyre label.
uniqueBidderCount:
type: integer
description: This integer value indicates the number of different eBay users who have placed one or more bids on an auction item. This field is only applicable to auction items.
format: int32
unitPrice:
description: 'This is 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. <br /><br />For example: <br /><br /><code>"unitPricingMeasure": "100g",<br /> "unitPrice": {<br /> "value": "7.99",<br /> "currency": "GBP"</code>'
$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. <br /><br />For example, the following tells the buyer that the item is 7.99 per 100 grams. <br /><br /><code>"unitPricingMeasure": "100g",<br /> "unitPrice": {<br /> "value": "7.99",<br /> "currency": "GBP"</code>'
warnings:
type: array
description: An array of warning messages. These types of errors do not prevent the method from executing but should be checked.
items:
$ref: '#/components/schemas/Error'
watchCount:
type: integer
description: The number of users that have added the item to their watch list.<br /><br /><span class="tablenote"> <strong>Note:</strong> This field is restricted to applications that have been granted permission to access this feature. You must submit an <a href="https://developer.ebay.com/my/support/tickets?tab=app-check ">App Check ticket</a> to request this access. In the App Check form, add a note to the <b>Application Title/Summary</b> and/or <b>Application Details</b> fields that you want access to Watch Count data in the Browse API.</span>
format: int32
description: The details of an item that can be purchased.
ItemGroup:
type: object
properties:
commonDescriptions:
type: array
description: An array of containers for a description and the item IDs of all the items that have this exact description. Often the item variations within an item group all have the same description. Instead of repeating this description in the item details of each item, a description that is shared by at least one other item is returned in this container. If the description is unique, it is returned in the <b> items.description</b> field.
items:
$ref: '#/components/schemas/CommonDescriptions'
items:
type: array
description: An array of containers for all the item variation details, excluding the description.
items:
$ref: '#/components/schemas/Item'
warnings:
type: array
description: An array of warning messages. These types of errors do not prevent the method from executing but should be checked.
items:
$ref: '#/components/schemas/Error'
description: The type that defines the fields for the item details.
ItemGroupSummary:
type: object
properties:
itemGroupAdditionalImages:
type: array
description: An array of containers with the URLs for images that are in addition to the primary image of the item group. The primary image is returned in the <b> itemGroupImage</b> field.
items:
$ref: '#/components/schemas/Image'
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. '
itemGroupId:
type: string
description: 'The unique identifier for the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. '
itemGroupImage:
description: 'The URL of the primary image of the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. '
$ref: '#/components/schemas/Image'
itemGroupTitle:
type: string
description: 'The title of the item that appears on the item group page. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. '
itemGroupType:
type: string
description: An enumeration value that indicates the type of the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:ItemGroupTypeEnum'>eBay API documentation</a>
description: 'The type that defines the fields for the details of each item in an item group. 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 the other items in the group are the children, such as the blue shirt size L, red shirt size M, etc. <br /><br /><span class="tablenote"><b> Note: </b> This container is returned only if the <b> item_id</b> in the request is an item group (parent ID of an item with variations).</span>'
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. <br /><br /><b>Restriction:</b> This field is populated in the <b> search</b> method response <i> only</i> when <b> fieldgroups</b> = <code>EXTENDED</code>.
country:
type: string
description: The two-letter <a href="https://www.iso.org/iso-3166-country-codes.html ">ISO 3166</a> standard code that indicates the country in which the item is located. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CountryCodeEnum'>eBay API documentation</a>
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 (or zip code in US) for items when they are listed. The postal code is used for calculating proximity searches. It is anonymized when returned in <b>itemLocation.postalCode</b> 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).
ItemReturnTerms:
type: object
properties:
extendedHolidayReturnsOffered:
type: boolean
description: This indicates if the seller has enabled the Extended Holiday Returns feature on the item. Extended Holiday Returns are only applicable during the US holiday season, and gives buyers extra time to return an item. This 'extra time' will typically extend beyond what is set through the <b> returnPeriod</b> value.
refundMethod:
type: string
description: 'An enumeration value that indicates how a buyer is refunded when an item is returned. <br><br><b> Valid Values: </b> MONEY_BACK or MERCHANDISE_CREDIT <br /><br />Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:RefundMethodEnum''>eBay API documentation</a>'
restockingFeePercentage:
type: string
description: This string field indicates the restocking fee percentage that the seller has set on the item. Sellers have the option of setting no restocking fee for an item, or they can set the percentage to 10, 15, or 20 percent. So, if the cost of the item was $100, and the restocking percentage was 20 percent, the buyer would be charged $20 to return that item, so instead of receiving a $100 refund, they would receive $80 due to the restocking fee.
returnInstructions:
type: string
description: Text written by the seller describing what the buyer needs to do in order to return the item.
returnMethod:
type: string
description: 'An enumeration value that indicates the alternative methods for a full refund when an item is returned. This field is returned if the seller offers the buyer an item replacement or exchange instead of a monetary refund. <br><br><b> Valid Values: </b> <ul><li><b> REPLACEMENT</b> - Indicates that the buyer has the option of receiving money back for the returned item, or they can choose to have the seller replace the item with an identical item.</li> <li><b> EXCHANGE</b> - Indicates that the buyer has the option of receiving money back for the returned item, or they can exchange the item for another similar item.</li></ul> Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:ReturnMethodEnum''>eBay API documentation</a>'
returnPeriod:
description: The amount of time the buyer has to return the item after the purchase date.
$ref: '#/components/schemas/TimeDuration'
returnsAccepted:
type: boolean
description: Indicates whether the seller accepts returns for the item.
returnShippingCostPayer:
type: string
description: 'This enumeration value indicates whether the buyer or seller is responsible for return shipping costs when an item is returned. <br><br><b> Valid Values: </b> <ul><li><b> SELLER</b> - Indicates the seller will pay for the shipping costs to return the item.</li> <li><b> BUYER</b> - Indicates the buyer will pay for the shipping costs to return the item.</li> </ul> Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:ReturnShippingCostPayerEnum''>eBay API documentation</a>'
description: The type that defines the fields for the seller's return policy.
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 <b> image.imageUrl</b> 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, see <a href="https://pages.ebay.com/help/policies/adult-only.html " target="_blank">Adult items policy</a> for sellers and <a href="https://www.ebay.com/help/terms-conditions/default/searching-adult-items?id=4661 " target="_blank">Adult-Only items on eBay</a> for buyers.
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. <br><br><b> Values Returned:</b><ul><li><b>FIXED_PRICE</b> - Indicates the buyer can purchase the item for a set price using the Buy It Now button. </li> <li><b> AUCTION</b> - 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.</li> <li><b> BEST_OFFER</b> - Items where the buyer can send the seller a price they're willing to pay for the item. The seller can accept, reject, or send a counter offer. For details about Best Offer, see <a href="https://www.ebay.com/help/selling/listings/selling-buy-now/adding-best-offer-listing?id=4144 " target="_blank">Best Offer</a>.</li><li><b>CLASSIFIED_AD</b> - Indicates that the final sales transaction is to be completed outside of the eBay environment.</li></ul> Code so that your app gracefully handles any future changes to this list.
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 the item matches the <b>compatibility_filter</b> product attributes. <br><br><b> Valid Values: </b> EXACT or POSSIBLE <br /><br />Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityMatchEnum''>eBay API documentation</a>'
compatibilityProperties:
type: array
description: This container returns only the product attributes that are compatible with the item. These attributes were specified in the <b>compatibility_filter</b> 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, see <a href="https://developer.ebay.com/devzone/finding/callref/enums/conditionIdList.html " target="_blank">Item Condition IDs and Names</a>. <br /><br />Code so that your app gracefully handles any future changes to this list.</span>
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, see <a href="https://developer.ebay.com/devzone/finding/callref/enums/conditionIdList.html " target="_blank">Item Condition IDs and Names</a>. <br /><br />Code so that your app gracefully handles any future changes to this list.
currentBidPrice:
description: This container returns the current highest bid for an auction item. The <b> value</b> field shows the dollar value of the current highest bid, and the <b> currency</b> 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 <b> pickupPostalCode</b> 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 <a href="https://en.wikipedia.org/wiki/European_Union_energy_label ">European energy efficiency</a> rating (EEK) of the item. Energy efficiency ratings apply to products listed by commercial vendors in electronics categories only. <br /><br />Currently, this field is only applicable for the Germany site, and is only returned if the seller specified the energy efficiency rating through item specifics at listing time. Rating values include <code>A+++</code>, <code>A++</code>, <code>A+</code>, <code>A</code>, <code>B</code>, <code>C</code>, <code>D</code>, <code>E</code>, <code>F</code>, and <code>G</code>.
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. This field is only returned if the seller enables affiliate tracking for the item by including the <code><a href="/api-docs/buy/static/api-browse.html#Headers">X-EBAY-C-ENDUSERCTX</a></code> request header in the method. <br /> <br /><span class="tablenote"><b>Note: </b> eBay Partner Network, in order to receive a commission for your sales, you must use this URL to forward your buyer to the ebay.com site. </span>'
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.<br /><br /><span class="tablenote"><b> Note: </b>This field is not returned for Good ''Til Cancelled (GTC) listings.</span>'
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. <br /> <br /><span class="tablenote"> <b> Note: </b>This field is returned only for item groups.</span>'
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. <br /><br />Currently only the <code>SELLER_DEFINED_VARIATIONS</code> is supported and indicates this is an item group created by the seller. <br /> <br /><span class="tablenote"> <b> Note: </b>This field is returned only for item groups.</span><br /><br />Code so that your app gracefully handles any future changes to this list.'
itemHref:
type: string
description: 'The URI for the Browse API <a href="/api-docs/buy/browse/resources/item/methods/getItem">getItem</a> 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 where the item is listed. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:MarketplaceIdEnum'>eBay API documentation</a>
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 only returned 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.<br /><br />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:<ul><li>Pass the <a href="/api-docs/static/rest-request-components.html#HTTP"><code>X-EBAY-C-MARKETPLACE-ID</code></a> request header specifying the supported marketplace (such as <code>EBAY_GB</code>)</li><li>Pass the <code>contextualLocation</code> values for the supported marketplace in the <a href="/api-docs/buy/static/api-browse.html#Headers"><code>X-EBAY-C-ENDUSERCTX</code></a> request header</li><li>Specify the supported marketplace using the <a href="/api-docs/buy/static/ref-buy-browse-filters.html#deliveryCountry"><code>deliveryCountry</code></a> <b>filter</b> URI parameter (such as <code>filter=deliveryCountry:GB</code>)</li></ul><span class="tablenote"><b> Note: </b>For more information on VAT, refer to <a href="https://www.ebay.co.uk/help/listings/default/vat-obligations-eu?id=4650&st=12&pos=1&query=Your%20VAT%20obligations%20in%20the%20EU&intent=VAT">VAT Obligations in the EU</a>.</span>'
$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 <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:PriceDisplayConditionEnum'>eBay API documentation</a>
priorityListing:
type: boolean
description: This field is returned as <code>true</code> 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.<br /><br /><span class="tablenote"><b>Note:</b> Priority Listing is returned only with a Best Match sort and will not be returned for other sort options.</span>
qualifiedPrograms:
type: array
description: 'An array of the qualified programs available for the item, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION.<br /><br />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.<br /><br /><span class="tablenote"><b>Note: </b> eBay Plus is available only to buyers in Germany, Austria, and Australia marketplaces.</span><br /><br />The eBay <a href="https://pages.ebay.com/authenticity-guarantee/ " target="_blank">Authenticity Guarantee</a> 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 doesn''t give enough information but the description is too big. Surfacing the <b>shortDescription</b> can often provide buyers with the additional information that could help them make a buying decision. <br /><br />For example: <br /><br /> <code> "<b> title</b>": "Petrel U42W FPV Drone RC Quadcopter w/HD Camera Live Video One Key Off / Landing", <br />"<b>shortDescription</b>": "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.",</code> <br /><br /><b>Restriction: </b> This field is returned by the <b> search</b> method only when <b> fieldgroups</b> = <code>EXTENDED</code>.'
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. <br><br><b>Maximum Length: </b> 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. See the <a href="https://pages.ebay.com/topratedplus/index.html " target="_blank">Top Rated Plus Items </a> and <a href="https://pages.ebay.com/help/sell/top-rated.html " target="_blank">Becoming a Top Rated Seller and qualifying for Top Rated Plus</a> help topics for more information.'
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. <br /><br />For example: <br /><br /><code>"unitPricingMeasure": "100g",<br /> "unitPrice": {<br /> "value": "7.99",<br /> "currency": "GBP"</code>'
$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. <br /><br />For example, the following tells the buyer that the item is 7.99 per 100 grams. <br /><br /><code>"unitPricingMeasure": "100g",<br /> "unitPrice": {<br /> "value": "7.99",<br /> "currency": "GBP"</code>'
watchCount:
type: integer
description: The number of users that have added the item to their watch list.<br /><br /><span class="tablenote"> <strong>Note:</strong> This field is restricted to applications that have been granted permission to access this feature. You must submit an <a href="https://developer.ebay.com/my/support/tickets?tab=app-check ">App Check ticket</a> to request this access. In the App Check form, add a note to the <b>Application Title/Summary</b> and/or <b>Application Details</b> fields that you want access to Watch Count data in the Browse API.</span>
format: int32
description: The type that defines the fields for the details of a specific item.
Items:
type: object
properties:
items:
type: array
description: An arraylist of all the items.
items:
$ref: '#/components/schemas/CoreItem'
total:
type: integer
description: The total number of items retrieved.
format: int32
warnings:
type: array
description: An array of warning messages. These types of errors do not prevent the method from executing but should be checked.
items:
$ref: '#/components/schemas/Error'
description: Container for a list of items.
LegalAddress:
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 is not always used, but can be used for 'Suite Number' or 'Apt Number'.
city:
type: string
description: The city of the address.
country:
type: string
description: The two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " target="_blank">ISO 3166</a> standard of the country of the address. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CountryCodeEnum'>eBay API documentation</a>
countryName:
type: string
description: The name of the country of the address.
county:
type: string
description: The name of the county of the address.
postalCode:
type: string
description: The postal code of the address.
stateOrProvince:
type: string
description: The state or province of the address.
description: Type that defines the fields for the seller's address.
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 <b> originalPrice</b> 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. <br /><br /><span class="tablenote"><b>Note: </b> The pricing treatment affects the way and where the discounted price can be displayed.</span> For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:PriceTreatmentEnum''>eBay API documentation</a>'
description: The type that defines the fields that describe a seller discount.
PaymentMethod:
type: object
properties:
paymentMethodType:
type: string
description: The payment method type, such as credit card or cash. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:PaymentMethodTypeEnum'>eBay API documentation</a>
paymentMethodBrands:
type: array
description: The payment method brands, including the payment method brand type and logo image.
items:
$ref: '#/components/schemas/PaymentMethodBrand'
paymentInstructions:
type: array
description: The payment instructions for the buyer, such as <i>cash in person</i> or <i>contact seller</i>.
items:
type: string
description: ' For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:PaymentInstructionEnum''>eBay API documentation</a>'
sellerInstructions:
type: array
description: The seller instructions to the buyer, such as <i>accepts credit cards</i> or <i>see description</i>.
items:
type: string
description: ' For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:SellerInstructionEnum''>eBay API documentation</a>'
PaymentMethodBrand:
type: object
properties:
paymentMethodBrandType:
type: string
description: The payment method brand, such as Visa or PayPal. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:PaymentMethodBrandEnum'>eBay API documentation</a>
logoImage:
description: 'The details of the logo image, such as the size and URL.<br /><br /><span class="tablenote"> <b> Note: </b> Currently, only the <b>imageUrl</b> is populated.</span>'
$ref: '#/components/schemas/Image'
PickupOptionSummary:
type: object
properties:
pickupLocationType:
type: string
description: This container returns the local pickup options available to the buyer. Possible values are <code>ARRANGED_LOCATION</code> and <code>STORE</code>.
description: The type that defines the fields for the local pickup options that are available for the item. It is used by the <b> pickupOptions</b> container.
Price:
type: object
properties:
convertedFromCurrency:
type: string
description: The three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank">ISO 4217</a> code representing the currency of the amount in the <b> convertedFromValue</b> field. This value is the pre-conversion currency. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CurrencyCodeEnum'>eBay API documentation</a>
convertedFromValue:
type: string
description: The monetary amount before any conversion is performed, in the currency specified by the <b> convertedFromCurrency</b> field. This value is the pre-conversion amount. The <b> value</b> field contains the converted amount of this value, in the currency specified by the <b> currency</b> field.
currency:
type: string
description: The three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank">ISO 4217</a> code representing the currency of the amount in the <b> value</b> field. If currency conversion/localization was performed, this is the post-conversion currency of the amount in the <b> value</b> field.<br /><br /><b> Default:</b> The currency of the user's country. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CurrencyCodeEnum'>eBay API documentation</a>
value:
type: string
description: The amount of the currency specified in the <b> currency</b> field. The value of <b> currency</b> defaults to the standard currency used by the country of the eBay site offering the item. If currency conversion/localization was performed, this is the post-conversion amount.<br /><br /><b> Default:</b> The currency of the user's country.
description: The type that defines the fields for the monetary value and currency of the price of the item.
Product:
type: object
properties:
additionalImages:
type: array
description: 'An array of containers with the URLs for the product images that are in addition to the primary image. '
items:
$ref: '#/components/schemas/Image'
additionalProductIdentities:
type: array
description: An array of product identifiers associated with the item. This container is returned if the seller has associated the eBay Product Identifier (ePID) with the item and in the request <b> fieldgroups</b> is set to <code>PRODUCT</code>.
items:
$ref: '#/components/schemas/AdditionalProductIdentity'
aspectGroups:
type: array
description: An array of containers for the product aspects. Each group contains the aspect group name and the aspect name/value pairs.
items:
$ref: '#/components/schemas/AspectGroup'
brand:
type: string
description: The brand associated with product. To identify the product, this is always used along with MPN (manufacturer part number).
description:
type: string
description: The rich description of an eBay product, which might contain HTML.
gtins:
type: array
description: An array of all the possible GTINs values associated with the product. A GTIN is a unique Global Trade Item number of the item as defined by <a href="https://www.gtin.info " target="_blank">https://www.gtin.info</a>. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.
items:
type: string
image:
description: The primary image of the product. This is often a stock photo.
$ref: '#/components/schemas/Image'
mpns:
type: array
description: An array of all possible MPN values associated with the product. A MPNs is manufacturer part number of the product. To identify the product, this is always used along with brand.
items:
type: string
title:
type: string
description: The title of the product.
description: The type that defines the fields for the product information of the item.
ProductIdentity:
type: object
properties:
identifierType:
type: string
description: The type of product identifier, such as UPC and EAN.
identifierValue:
type: string
description: The product identifier value.
description: The type that defines the fields for the product identifier type/value pairs of product associated with an item.
RatingHistogram:
type: object
properties:
count:
type: integer
description: The total number of user ratings that the product has received.
format: int32
rating:
type: string
description: This is the average rating for the product. As part of a product review, users rate the product. Products are rated from one star (terrible) to five stars (excellent), with each star having a corresponding point value - one star gets 1 point, two stars get 2 points, and so on. If a product had one four-star rating and one five-star rating, its average rating would be <code> 4.5</code>, and this is the value that would appear in this field.
description: The type that defines the fields for product ratings. Only products that are in the eBay product catalog can be reviewed and rated.
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.
Region:
type: object
properties:
regionName:
type: string
description: 'A localized text string that indicates the name of the region. Taxes are generally charged at the state/province level or at the country level in the case of VAT tax. '
regionType:
type: string
description: 'An enumeration value that indicates the type of region for the tax jurisdiction. <br><br><b> Valid Values: </b> <ul><li><b> STATE_OR_PROVINCE </b> - Indicates the region is a state or province within a country, such as California or New York in the US, or Ontario or Alberta in Canada.</li><li><b> COUNTRY </b> - Indicates the region is a single country.</li></ul> Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/ba:RegionTypeEnum''>eBay API documentation</a>'
description: This type is used to provide region details for a tax jurisdiction.
RemoteShopcartResponse:
type: object
properties:
cartItems:
type: array
description: An array of the items in the member's eBay cart.
items:
$ref: '#/components/schemas/CartItem'
cartSubtotal:
description: This is the cost of all the items in the member's eBay cart. This does not include taxes, shipping costs, discounts, etc. It is the sum of each item's <b> price</b> * <b> quantity</b>.
$ref: '#/components/schemas/Amount'
cartWebUrl:
type: string
description: The URL of the member's eBay cart.
unavailableCartItems:
type: array
description: An array of items in the cart that are unavailable. This can be for a variety of reasons such as, when the listing has ended or the item is out of stock. Because a cart never expires, these items will remain in the cart until they are removed.
items:
$ref: '#/components/schemas/CartItem'
warnings:
type: array
description: An array of warning messages. These type of errors do not prevent the call from executing but should be checked.
items:
$ref: '#/components/schemas/Error'
description: The type that defines the fields and containers for the member's eBay cart information.
RemoveCartItemInput:
type: object
properties:
cartItemId:
type: string
description: 'The identifier of the item in the cart to be removed. This ID is generated when the item was added to the cart. '
description: The type that defines the fields for the <b>removeItem</b> request.
ReviewRating:
type: object
properties:
averageRating:
type: string
description: The average rating given to a product based on customer reviews.
ratingHistograms:
type: array
description: An array of containers for the product rating histograms that shows the review counts and the product rating.
items:
$ref: '#/components/schemas/RatingHistogram'
reviewCount:
type: integer
description: The total number of reviews for the item.
format: int32
description: The type that defines the fields for the rating of a product review.
SearchByImageRequest:
type: object
properties:
image:
type: string
description: The Base64 string of the image.
description: The type that defines the fields for the image information.
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. <br /><br />The following example of the <b> search</b> method returns items 1 thru 5 from the list of items found. <br /><br /><code>https://api.ebay.com/buy/v1/item_summary/search?q=shirt&limit=5&offset=0</code>.
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 <b>limit</b> 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. <br /><br />The following example of the <b> search</b> method returns items 5 thru 10 from the list of items found.<br /> <br /><code>https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=10 </code>
offset:
type: integer
description: This value indicates the <b>offset</b> used for current page of items being returned. Assume the initial request used an <b>offset</b> of <code>0</code> and a <b>limit</b> of <code>3</code>. Then in the first page of results, this value would be <code>0</code>, and items 1-3 are returned. For the second page, this value is <code>3</code> 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. <br /><br />The following example of the <b> search</b> method returns items 1 thru 5 from the list of items found, which would be the first set of items returned.<br /> <br /><code>https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=0</code>
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.
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 <em> pages</em> where each page has 0 or more items. '
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. <br /><br />This field is returned only on the following sites. <br /><br />EBAY_AT, EBAY_BE, EBAY_CH, EBAY_DE, EBAY_ES, EBAY_FR, EBAY_GB, EBAY_IE, EBAY_IT, EBAY_PL <br /><br /><b> Valid Values:</b> BUSINESS or INDIVIDUAL <br /><br />Code so that your app gracefully handles any future changes to this list. '
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 <b> item_summary</b> resource.
SellerCustomPolicy:
type: object
properties:
description:
type: string
description: The seller-defined description of the policy.
label:
type: string
description: The seller-defined label for an individual custom policy.
type:
type: string
description: The type of custom policy, such as PRODUCT_COMPLIANCE or TAKE_BACK. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:SellerCustomPolicyTypeEnum'>eBay API documentation</a>
description: The container for custom policies that apply to a listed item.
SellerDetail:
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: 'This 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 the following countries: <br /><br /> This field is returned only on the following sites. <br /><br />EBAY_AT, EBAY_BE, EBAY_CH, EBAY_DE, EBAY_ES, EBAY_FR, EBAY_GB, EBAY_IE, EBAY_IT, EBAY_PL <br /><br /><b> Valid Values:</b> BUSINESS or INDIVIDUAL <br /><br />Code so that your app gracefully handles any future changes to this list. '
sellerLegalInfo:
description: The container with the seller's contact info and fields that are required by law.
$ref: '#/components/schemas/SellerLegalInfo'
username:
type: string
description: The user name created by the seller for use on eBay.
description: The type that defines the fields for basic and detailed information about the seller of the item returned by the <b> item</b> resource.
SellerLegalInfo:
type: object
properties:
email:
type: string
description: The seller's business email address.
fax:
type: string
description: The seller' business fax number.
imprint:
type: string
description: This is a free-form string created by the seller. This is information often found on business cards, such as address. This is information used by some countries.
legalContactFirstName:
type: string
description: The seller's first name.
legalContactLastName:
type: string
description: The seller's last name.
name:
type: string
description: The name of the seller's business.
phone:
type: string
description: The seller's business phone number.
registrationNumber:
type: string
description: The seller's registration number. This is information used by some countries.
sellerProvidedLegalAddress:
description: The container that returns the seller's address to be used to contact them.
$ref: '#/components/schemas/LegalAddress'
termsOfService:
type: string
description: This is a free-form string created by the seller. This is the seller's terms or condition, which is in addition to the seller's return policies.
vatDetails:
type: array
description: An array of the seller's VAT (value added tax) IDs and the issuing country. VAT is a tax added by some European countries.
items:
$ref: '#/components/schemas/VatDetail'
description: The type that defines the fields for the contact information for a seller.
ShipToLocation:
type: object
properties:
country:
type: string
description: The two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " target="_blank">ISO 3166</a> standard of the country for where the item is to be shipped. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CountryCodeEnum'>eBay API documentation</a>
postalCode:
type: string
description: The zip code (postal code) for where the item is to be shipped.
description: The type that defines the fields for the country and postal code of where an item is to be shipped.
ShipToLocations:
type: object
properties:
regionExcluded:
type: array
description: An array of containers that express the large geographical regions, countries, state/provinces, or special locations within a country where the seller is not willing to ship to.
items:
$ref: '#/components/schemas/ShipToRegion'
regionIncluded:
type: array
description: An array of containers that express the large geographical regions, countries, or state/provinces within a country where the seller is willing to ship to. Prospective buyers must look at the shipping regions under this container, as well as the shipping regions that are under the <b>regionExcluded</b> to see where the seller is willing to ship items. Sellers can specify that they ship 'Worldwide', but then add several large geographical regions (e.g. Asia, Oceania, Middle East) to the exclusion list, or sellers can specify that they ship to Europe and Africa, but then add several individual countries to the exclusion list.
items:
$ref: '#/components/schemas/ShipToRegion'
description: The type that defines the fields that include and exclude geographic regions affecting where the item can be shipped. The seller defines these regions when listing the item.
ShipToRegion:
type: object
properties:
regionId:
type: string
description: 'The unique identifier of the shipping region. The value returned here is dependent on the corresponding <b>regionType</b> value. The <b>regionId</b> value for a region does not vary based on the eBay marketplace. However, the corresponding <b>regionName</b> value for a region is a localized, text-based description of the shipping region. <br><br> If the <b>regionType</b> value is <code>WORLDWIDE</code>, the <b>regionId</b> value will also be <code>WORLDWIDE</code>.<br><br> If the <b>regionType</b> value is <code>WORLD_REGION</code>, the <b>regionId</b> value will be one of the following: <code>AFRICA</code>, <code>AMERICAS</code>, <code>ASIA</code>, <code>AUSTRALIA</code>, <code>CENTRAL_AMERICA_AND_CARIBBEAN</code>, <code>EUROPE</code>, <code>EUROPEAN_UNION</code>, <code>GREATER_CHINA</code>, <code>MIDDLE_EAST</code>, <code>NORTH_AMERICA</code>, <code>OCEANIA</code>, <code>SOUTH_AMERICA</code>, <code>SOUTHEAST_ASIA</code> or <code>CHANNEL_ISLANDS</code>.<br><br>If the <b>regionType</b> value is <code>COUNTRY</code>, the <b>regionId</b> value will be the two-letter code for the country, as defined in the <a href="https://www.iso.org/iso-3166-country-codes.html " target="_blank">ISO 3166</a> standard.<br><br>If the <b>regionType</b> value is <code>STATE_OR_PROVINCE</code>, the <b>regionId</b> value will either be the two-letter code for US states and DC (as defined on this <a href="https://www.ssa.gov/international/coc-docs/states.html " target="_blank">Social Security Administration</a> page), or the two-letter code for Canadian provinces (as defined by this <a href="https://www.canadapost.ca/tools/pg/manual/PGaddress-e.asp?ecid=murl10006450#1442131 " target="_blank">Canada Post</a> page).<br><br>If the <b>regionType</b> value is <code>COUNTRY_REGION</code>, the <b>regionId</b> value may be one of following: <code>_AH</code> (if a seller is not willing to ship to Alaska/Hawaii), <code>_PR</code> (if the seller is not willing to ship to US Protectorates), <code>_AP</code> (if seller is not willing to ship to a US Army or Fleet Post Office), and <code>PO_BOX</code> (if the seller is not willing to ship to a Post Office Box).'
regionName:
type: string
description: 'A localized text string that indicates the name of the shipping region. The value returned here is dependent on the corresponding <b>regionType</b> value. <br><br> If the <b>regionType</b> value is <code>WORLDWIDE</code>, the <b>regionName</b> value will show <code>Worldwide</code>.<br><br> If the <b>regionType</b> value is <code>WORLD_REGION</code>, the <b>regionName</b> value will be a localized text string for one of the following large geographical regions: Africa, Americas, Asia, Australia, Central America and Caribbean, Europe, European Union, Greater China, Middle East, North America, Oceania, South America, Southeast Asia, or Channel Islands.<br><br>If the <b>regionType</b> value is <code>COUNTRY</code>, the <b>regionName</b> value will be a localized text string for any country in the world.<br><br>If the <b>regionType</b> value is <code>STATE_OR_PROVINCE</code>, the <b>regionName</b> value will be a localized text string for any US state or Canadian province. <br><br>If the <b>regionType</b> value is <code>COUNTRY_REGION</code>, the <b>regionName</b> value may be a localized version of one of the following: Alaska/Hawaii, US Protectorates, APO/FPO (Army or Fleet Post Office), or PO BOX.'
regionType:
type: string
description: 'An enumeration value that indicates the level or type of shipping region. <br><br><b> Valid Values: </b> <ul><li><b> COUNTRY_REGION </b> - Indicates the region is a domestic region or special location within a country.</li><li><b> STATE_OR_PROVINCE </b> - Indicates the region is a state or province within a country, such as California or New York in the US, or Ontario or Alberta in Canada.</li><li><b> COUNTRY </b> - Indicates the region is a single country.</li><li><b> WORLD_REGION </b> - Indicates the region is a world region, such as Africa, the Middle East, or Southeast Asia.</li><li><b> WORLDWIDE </b> - Indicates the region is the entire world. This value is only applicable for included shiping regions, and not excluded shipping regions.</li></ul> For more detail on the actual <b>regionName</b>/<b>regionId</b> values that will be returned based on the <b>regionType</b> value, see the <a href="/api-docs/buy/browse/resources/item/methods/getItem#response.shipToLocations.regionExcluded.regionId">regionId</a> and/or <a href="/api-docs/buy/browse/resources/item/methods/getItem#response.shipToLocations.regionExcluded.regionName">regionName</a> field descriptions.<br><br> Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/ba:RegionTypeEnum''>eBay API documentation</a>'
description: This type is used provide details about included and excluded shipping regions.
ShippingOption:
type: object
properties:
additionalShippingCostPerUnit:
description: Any per item additional shipping costs for a multi-item purchase. For example, let's say the shipping cost for a power cord is $3. But for an additional cord, the shipping cost is only $1. So if you bought 3 cords, the <b> shippingCost</b> would be $3 and this value would be $2 ($1 for each additional item).
$ref: '#/components/schemas/ConvertedAmount'
cutOffDateUsedForEstimate:
type: string
description: The deadline date that the item must be purchased by in order to be received by the buyer within the delivery window (<b> maxEstimatedDeliveryDate</b> and <b> minEstimatedDeliveryDate</b> fields). This field is returned only for items that are eligible for 'Same Day Handling'. For these items, the value of this field is what is displayed in the <b> Delivery</b> line on the View Item page. <br /><br />This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer.
fulfilledThrough:
type: string
description: If the item is being shipped by the eBay <a href="https://pages.ebay.com/seller-center/shipping/global-shipping-program.html ">Global Shipping program</a>, this field returns <code>GLOBAL_SHIPPING</code>.<br /><br />If the item is being shipped using the eBay International Shipping program, this field returns <code>INTERNATIONAL_SHIPPING</code>. <br /><br />Otherwise, this field is null. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:FulfilledThroughEnum'>eBay API documentation</a>
guaranteedDelivery:
type: boolean
description: Indicates if the seller has committed to shipping the item with eBay Guaranteed Delivery. With eBay Guaranteed Delivery, the seller is committed to getting the line item to the buyer within 4 business days or less. See the <a href="https://www.ebay.com/help/buying/shipping-delivery/buying-items-ebay-guaranteed-delivery?id=4641 ">Buying items with eBay Guaranteed Delivery</a> help topic for more details about eBay Guaranteed Delivery.
importCharges:
description: The <a href="https://pages.ebay.com/seller-center/shipping/global-shipping-program.html ">Global Shipping Program</a> import charges for this item.
$ref: '#/components/schemas/ConvertedAmount'
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. <br /> <br /> <span class="tablenote"> <b> Note: </b> For the best accuracy, always include the location of where the item is be shipped in the <code> contextualLocation</code> values of the <a href="/api-docs/buy/static/api-browse.html#Headers"> <code>X-EBAY-C-ENDUSERCTX</code></a> request header.</span> '
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. <br /> <br /><span class="tablenote"> <b> Note: </b> For the best accuracy, always include the location of where the item is be shipped in the <code> contextualLocation</code> values of the <a href="/api-docs/buy/static/api-browse.html#Headers"> <code>X-EBAY-C-ENDUSERCTX</code></a> request header.</span>'
quantityUsedForEstimate:
type: integer
description: The number of items used when calculating the estimation information.
format: int32
shippingCarrierCode:
type: string
description: The name of the shipping provider, such as FedEx, or USPS.
shippingCost:
description: 'The final shipping cost for all the items after all discounts are applied.<br /><br /><span class="tablenote"><b> Note: </b>The cost does include the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the <a href="/api-docs/static/rest-request-components.html#HTTP"><code>X-EBAY-C-MARKETPLACE-ID</code></a> request header specifying the supported marketplace (such as <code>EBAY_GB</code>) to see the VAT-inclusive cost. For more information on VAT, refer to <a href="https://www.ebay.co.uk/help/listings/default/vat-obligations-eu?id=4650&st=12&pos=1&query=Your%20VAT%20obligations%20in%20the%20EU&intent=VAT">VAT Obligations in the EU</a>.</span>'
$ref: '#/components/schemas/ConvertedAmount'
shippingCostType:
type: string
description: 'Indicates the class of the shipping cost. <br /><br /><b> Valid Values: </b> FIXED or CALCULATED <br /><br />Code so that your app gracefully handles any future changes to this list. '
shippingServiceCode:
type: string
description: The type of shipping service. For example, USPS First Class.
shipToLocationUsedForEstimate:
description: The container that returns the country and postal code of where the item is to be shipped. These values come from the <code>contextualLocation</code> values in the <a href="/api-docs/buy/static/api-browse.html#Headers"> <code>X-EBAY-C-ENDUSERCTX</code></a> request header. If the header is not submitted, marketplace is used.
$ref: '#/components/schemas/ShipToLocation'
trademarkSymbol:
type: string
description: Any trademark symbol, such as ™ or ®, that needs to be shown in superscript next to the shipping service name.
type:
type: string
description: The type of a shipping option, such as EXPEDITED, ONE_DAY, STANDARD, ECONOMY, PICKUP, etc.
description: The type that defines the fields for the details of a shipping provider.
ShippingOptionSummary:
type: object
properties:
guaranteedDelivery:
type: boolean
description: Indicates if the seller has committed to shipping the item with eBay Guaranteed Delivery. With eBay Guaranteed Delivery, the seller is committed to getting the line item to the buyer within 4 business days or less. See the <a href="https://www.ebay.com/help/buying/shipping-delivery/buying-items-ebay-guaranteed-delivery?id=4641 ">Buying items with eBay Guaranteed Delivery</a> help topic for more details about eBay Guaranteed Delivery.
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. <br /> <br /> <span class="tablenote"> <b> Note: </b> For the best accuracy, always include the <code> contextualLocation</code> values in the <a href="/api-docs/buy/static/api-browse.html#Headers"> <code>X-EBAY-C-ENDUSERCTX</code></a> request header.</span>'
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. <br /> <br /><span class="tablenote"> <b> Note: </b> For the best accuracy, always include the <code> contextualLocation</code> values in the <a href="/api-docs/buy/static/api-browse.html#Headers"> <code>X-EBAY-C-ENDUSERCTX</code></a> request header.</span>'
shippingCost:
description: 'This is the estimated price to ship the item.<br /><br />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:<ul><li>Pass the <a href="/api-docs/static/rest-request-components.html#HTTP"><code>X-EBAY-C-MARKETPLACE-ID</code></a> request header specifying the supported marketplace (such as <code>EBAY_GB</code>)</li><li>Pass the <code>contextualLocation</code> values for the supported marketplace in the <a href="/api-docs/buy/static/api-browse.html#Headers"><code>X-EBAY-C-ENDUSERCTX</code></a> request header</li><li>Specify the supported marketplace using the <a href="/api-docs/buy/static/ref-buy-browse-filters.html#deliveryCountry"><code>deliveryCountry</code></a> <b>filter</b> URI parameter (such as <code>filter=deliveryCountry:GB</code>)</li></ul><span class="tablenote"><b> Note: </b>For more information on VAT, refer to <a href="https://www.ebay.co.uk/help/listings/default/vat-obligations-eu?id=4650&st=12&pos=1&query=Your%20VAT%20obligations%20in%20the%20EU&intent=VAT">VAT Obligations in the EU</a>.</span>'
$ref: '#/components/schemas/ConvertedAmount'
shippingCostType:
type: string
description: Indicates the type of shipping used to ship the item. Possible values are <code> FIXED</code> (flat-rate shipping) and <code> CALCULATED</code> (shipping cost calculated based on item and buyer location).
description: The type that defines the fields for the shipping information.
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 <code> mi</code> or <code> km</code>.
value:
type: string
description: This value indicates the distance (measured in the measurement unit in the <b> unitOfMeasure</b> 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. '
TaxJurisdiction:
type: object
properties:
region:
description: The region of the tax jurisdiction.
$ref: '#/components/schemas/Region'
taxJurisdictionId:
type: string
description: The identifier of the tax jurisdiction.
description: The type that defines the fields for the tax jurisdiction details.
Taxes:
type: object
properties:
ebayCollectAndRemitTax:
type: boolean
description: 'This field is only returned if <code>true</code>, and indicates that eBay will collect tax (sales tax, Goods and Services tax, or VAT) for at least one line item in the order, and remit the tax to the taxing authority of the buyer''s residence. '
includedInPrice:
type: boolean
description: This indicates if tax was applied for the cost of the item.
shippingAndHandlingTaxed:
type: boolean
description: This indicates if tax is applied for the shipping cost.
taxJurisdiction:
description: The container that returns the tax jurisdiction.
$ref: '#/components/schemas/TaxJurisdiction'
taxPercentage:
type: string
description: The percentage of tax.
taxType:
type: string
description: This field indicates the type of tax that may be collected for the item. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/gct:TaxType'>eBay API documentation</a>
description: The type that defines the tax fields.
TimeDuration:
type: object
properties:
unit:
type: string
description: 'An enumeration value that indicates the units (such as hours) of the time span. The enumeration value in this field defines the period of time being used to measure the duration. <br><br><b> Valid Values: </b> YEAR, MONTH, DAY, HOUR, CALENDAR_DAY, BUSINESS_DAY, MINUTE, SECOND, or MILLISECOND <br /><br />Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/ba:TimeDurationUnitEnum''>eBay API documentation</a>'
value:
type: integer
description: 'Retrieves the duration of the time span (no units).The value in this field indicates the number of years, months, days, hours, or minutes in the defined period. '
format: int32
description: The type that defines the fields for a period of time in the time-measurement units supplied.
TypedNameValue:
type: object
properties:
name:
type: string
description: The text representing the name of the aspect for the name/value pair, such as Color.
type:
type: string
description: 'This indicates if the value being returned is a string or an array of values. <br><br><b> Valid Values: </b> <ul><li><b> STRING</b> - Indicates the value returned is a string.</li> <li><b> STRING_ARRAY</b> - Indicates the value returned is an array of strings.</li></ul> Code so that your app gracefully handles any future changes to this list. For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/buy/browse/types/gct:ValueTypeEnum''>eBay API documentation</a>'
value:
type: string
description: The value of the aspect for the name/value pair, such as Red.
description: The type that defines the fields for the name/value pairs for item aspects.
UpdateCartItemInput:
type: object
properties:
cartItemId:
type: string
description: The identifier of the item in the cart to be updated. This ID is generated when the item was added to the cart.
quantity:
type: integer
description: The new quantity for the item that is being updated.
format: int32
description: The type that defines the fields for the <b>updateQuantity</b> request.
VatDetail:
type: object
properties:
issuingCountry:
type: string
description: The two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " target="_blank">ISO 3166</a> standard of the country issuing the seller's VAT (value added tax) ID. VAT is a tax added by some European countries. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/buy/browse/types/ba:CountryCodeEnum'>eBay API documentation</a>
vatId:
type: string
description: The seller's VAT (value added tax) ID. VAT is a tax added by some European countries.
description: The type the defines the fields for the VAT (value add tax) information.
securitySchemes:
api_auth:
type: oauth2
description: The security definitions for this API. Please check individual operations for applicable scopes.
flows:
clientCredentials:
tokenUrl: https://api.ebay.com/identity/v1/oauth2/token
scopes:
https://api.ebay.com/oauth/api_scope/buy.item.bulk: Retrieve eBay items in bulk.
https://api.ebay.com/oauth/api_scope: View public data from eBay
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/buy.shopping.cart: ' This scope would allow signed in user to access shopping carts'