api-specs/commerce_catalog_v1_beta_oas3.yaml
---
openapi: "3.0.0"
info:
title: "Catalog API"
description: "The Catalog API allows users to search for and locate an eBay catalog\
\ product that is a direct match for the product that they wish to sell. Listing\
\ against an eBay catalog product helps insure that all listings (based off of\
\ that catalog product) have complete and accurate information. In addition to\
\ helping to create high-quality listings, another benefit to the seller of using\
\ catalog information to create listings is that much of the details of the listing\
\ will be prefilled, including the listing title, the listing description, the\
\ item specifics, and a stock image for the product (if available). Sellers will\
\ not have to enter item specifics themselves, and the overall listing process\
\ is a lot faster and easier."
contact:
name: "eBay Inc,"
license:
name: "eBay API License Agreement"
url: "https://go.developer.ebay.com/api-license-agreement"
version: "v1_beta.5.0"
servers:
- url: "https://api.ebay.com{basePath}"
description: "Production"
variables:
basePath:
default: "/commerce/catalog/v1_beta"
paths:
/product/{epid}:
get:
tags:
- "product"
description: "This method retrieves details of the catalog product identified\
\ by the eBay product identifier (ePID) specified in the request. These details\
\ include the product's title and description, aspects and their values, associated\
\ images, applicable category IDs, and any recognized identifiers that apply\
\ to the product. <br /><br /> For a new listing, you can use the <b>search</b>\
\ method to identify candidate products on which to base the listing, then\
\ use the <b>getProduct</b> method to present the full details of those candidate\
\ products to the seller to make a a final selection."
operationId: "getProduct"
parameters:
- name: "X-EBAY-C-MARKETPLACE-ID"
in: "header"
description: "This method also uses the <code>X-EBAY-C-MARKETPLACE-ID</code>\
\ header to identify the seller's eBay marketplace. It is required for all\
\ marketplaces except EBAY_US, which is the default. <b>Note:</b> This method\
\ is limited to <code>EBAY_US</code>, <code>EBAY_AU</code>, <code>EBAY_CA</code>,\
\ and <code>EBAY_GB</code> values."
required: false
schema:
type: "string"
- name: "epid"
in: "path"
description: "The ePID of the product being requested. This value can be discovered\
\ by issuing the <b>search</b> method and examining the value of the <b>productSummaries.epid</b>\
\ field for the desired returned product summary."
required: true
schema:
type: "string"
responses:
200:
description: "OK"
content:
application/json:
schema:
$ref: "#/components/schemas/Product"
400:
description: "Bad Request"
x-response-codes:
errors:
75011:
domain: "API_CATALOG"
category: "REQUEST"
description: "The specified EPID value {epid} no longer exists. Its\
\ new value is {newepid}."
75010:
domain: "API_CATALOG"
category: "REQUEST"
description: "The specified EPID value {epid} was not found."
75015:
domain: "API_CATALOG"
category: "REQUEST"
description: "Insufficient permissions to fulfill the request."
75016:
domain: "API_CATALOG"
category: "REQUEST"
description: "The specified EPID value {epid} is no longer available."
75007:
domain: "API_CATALOG"
category: "REQUEST"
description: "Currently, the {marketplaceId} marketplace is not supported.\
\ The supported Marketplaces are: {allowedMarketplaces}."
500:
description: "Internal Server Error"
x-response-codes:
errors:
75000:
domain: "API_CATALOG"
category: "APPLICATION"
description: "There was a problem with an eBay internal system or\
\ process. Contact eBay developer support for assistance."
403:
description: "Forbidden"
404:
description: "Not Found"
security:
- api_auth:
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- "https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly"
/product_summary/search:
get:
tags:
- "product_summary"
description: "This method searches for and retrieves summaries of one or more\
\ products in the eBay catalog that match the search criteria provided by\
\ a seller. The seller can use the summaries to select the product in the\
\ eBay catalog that corresponds to the item that the seller wants to offer\
\ for sale. When a corresponding product is found and adopted by the seller,\
\ eBay will use the product information to populate the item listing. The\
\ criteria supported by <b>search</b> include keywords, product categories,\
\ and category aspects. To see the full details of a selected product, use\
\ the <b>getProduct</b> call. <br /><br /> In addition to product summaries,\
\ this method can also be used to identify <i>refinements</i>, which help\
\ you to better pinpoint the product you're looking for. A refinement consists\
\ of one or more <i>aspect</i> values and a count of the number of times that\
\ each value has been used in previous eBay listings. An aspect is a property\
\ (e.g. color or size) of an eBay category, used by sellers to provide details\
\ about the items they're listing. The <b>refinement</b> container is returned\
\ when you include the <b>fieldGroups</b> query parameter in the request with\
\ a value of <code>ASPECT_REFINEMENTS</code> or <code>FULL</code>. <br /><br\
\ /> <span style=\"padding: 15px 20px; display: block; border: 1px solid #cccccc\"\
><b>Example</b> <br />A seller wants to find a product that is \"gray\" in\
\ color, but doesn't know what term the manufacturer uses for that color.\
\ It might be <code>Silver</code>, <code>Brushed Nickel</code>, <code>Pewter</code>,\
\ or even <code>Grey</code>. The returned <b>refinement</b> container identifies\
\ all aspects that have been used in past listings for products that match\
\ your search criteria, along with all of the values those aspects have taken,\
\ and the number of times each value was used. You can use this data to present\
\ the seller with a histogram of the values of each aspect. The seller can\
\ see which color values have been used in the past, and how frequently they\
\ have been used, and selects the most likely value or values for their product.\
\ You issue the <b>search</b> method again with those values in the <b>aspect_filter</b>\
\ parameter to narrow down the collection of products returned by the call.</span>\
\ <br /><br /> Although all query parameters are optional, this method must\
\ include at least the <b>q</b> parameter, or the <b>category_ids</b>, <b>gtin</b>,\
\ or <b>mpn</b> parameter with a valid value. If you provide more than one\
\ of these parameters, they will be combined with a logical AND to further\
\ refine the returned collection of matching products. <br /><br /> <span\
\ class=\"tablenote\"><strong>Note:</strong> This method requires that certain\
\ special characters in the query parameters be percent-encoded: <br /><br\
\ /> <code>(space)</code> = <code>%20</code> <code>,</code>\
\ = <code>%2C</code> <code>:</code> =\
\ <code>%3A</code> <code>[</code> = <code>%5B</code>\
\ <code>]</code> = <code>%5D</code> <code>{</code>\
\ = <code>%7B</code> <code>|</code> =\
\ <code>%7C</code> <code>}</code> = <code>%7D</code>\
\ <br /><br /> This requirement applies to all query parameter values. However,\
\ for readability, method examples and samples in this documentation will\
\ not use the encoding.</span> <br /><br /> This method returns product summaries\
\ rather than the full details of the products. To retrieve the full details\
\ of a product, use the <b>getProduct</b> method with an ePID."
operationId: "search"
parameters:
- name: "X-EBAY-C-MARKETPLACE-ID"
in: "header"
description: "This method also uses the <code>X-EBAY-C-MARKETPLACE-ID</code>\
\ header to identify the seller's eBay marketplace. It is required for all\
\ marketplaces except EBAY_US, which is the default. <b>Note:</b> This method\
\ is limited to <code>EBAY_US</code>, <code>EBAY_AU</code>, <code>EBAY_CA</code>,\
\ and <code>EBAY_GB</code> values."
required: false
schema:
type: "string"
- name: "aspect_filter"
in: "query"
description: "An eBay category and one or more aspects of that category, with\
\ the values that can be used to narrow down the collection of products\
\ returned by this call. <br /><br /> Aspects are product attributes that\
\ can represent different types of information for different products. Every\
\ product has aspects, but different products have different sets of aspects.\
\ <br /><br /> You can determine appropriate values for the aspects by first\
\ submitting this method without this parameter. It will return either the\
\ <b>productSummaries.aspects</b> container, the <b>refinement.aspectDistributions</b>\
\ container, or both, depending on the value of the <b>fieldgroups</b> parameter\
\ in the request. The <b>productSummaries.aspects</b> container provides\
\ the category aspects and their values that are associated with each returned\
\ product. The <b>refinement.aspectDistributions</b> container provides\
\ information about the distribution of values of the set of category aspects\
\ associated with the specified categories. In both cases sellers can select\
\ from among the returned aspects to use with this parameter. <br /><br\
\ /> <span class=\"tablenote\"> <strong>Note:</strong> You can also use\
\ the Taxonomy API's <b>getItemAspectsForCategory</b> method to retrieve\
\ detailed information about aspects and their values that are appropriate\
\ for your selected category. </span> <br /><br /> The syntax for the <b>aspect_filter</b>\
\ parameter is as follows (on several lines for readability; <b>categoryId</b>\
\ is required): <br /><br /> <code>aspect_filter=categoryId:<i>category_id</i>,<br\
\ /> <i>aspect1</i>:{<i>valueA</i>|<i>valueB</i>|...},<br /> <i>aspect2</i>:{<i>valueC</i>|<i>valueD</i>|...},.</code>\
\ <br /><br /> A matching product must be within the specified category,\
\ and it must have least one of the values identified for every specified\
\ aspect. <br /><br /> <span class=\"tablenote\"> <strong>Note:</strong>\
\ Aspect names and values are case sensitive. </span> <br /><br /> Here\
\ is an example of an <b>aspect_filter</b> parameter in which <code>9355</code>\
\ is the category ID, <code>Color</code> is an aspect of that category,\
\ and <code>Black</code> and <code>White</code> are possible values of that\
\ aspect (on several lines for readability): <br /><br /> <code>GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?<br\
\ /> aspect_filter=categoryId:9355,Color:{White|Black}</code> <br /><br\
\ /> Here is the <b>aspect_filter</b> with required URL encoding and a second\
\ aspect (on several lines for readability): <br /><br /> <code>GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?<br\
\ /> aspect_filter=categoryId:9355,Color:%7BWhite%7CBlack%7D,<br /> Storage%20Capacity:%128GB%7C256GB%7D</code>\
\ <br /><br /> <span class=\"tablenote\"> <strong>Note:</strong> You cannot\
\ use the <b>aspect_filter</b> parameter in the same method with either\
\ the <b>gtin</b> parameter or the <b>mpn</b> parameter. </span> For implementation\
\ help, refer to eBay API documentation at https://developer.ebay.com/api-docs/commerce/catalog/types/catal:AspectFilter"
required: false
schema:
type: "string"
- name: "category_ids"
in: "query"
description: "<span class=\"tablenote\"> <strong>Important:</strong> Currently,\
\ only the first <b>category_id</b> value is accepted. </span> <br /><br\
\ /> One or more comma-separated category identifiers for narrowing down\
\ the collection of products returned by this call. <br /><br /> <span class=\"\
tablenote\"> <strong>Note:</strong> This parameter requires a valid category\
\ ID value. You can use the Taxonomy API's <b>getCategorySuggestions</b>\
\ method to retrieve appropriate category IDs for your product based on\
\ keywords. </span> <br /><br /> The syntax for this parameter is as follows:\
\ <br /><br /> <code>category_ids=<i>category_id1</i>,<i>category_id2</i>,.</code>\
\ <br /><br /> Here is an example of a method with the <b>category_ids</b>\
\ parameter: br /><br /> <code>GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?<br\
\ /> category_ids=178893</code> <br /><br /> <span class=\"tablenote\">\
\ <strong>Note:</strong> Although all query parameters are optional, this\
\ method must include at least the <b>q</b> parameter, or the <b>category_ids</b>,\
\ <b>gtin</b>, or <b>mpn</b> parameter with a valid value. <br /><br />\
\ If you provide only the <b>category_ids</b> parameter, you cannot specify\
\ a top-level (L1) category. </span>"
required: false
schema:
type: "string"
- name: "fieldgroups"
in: "query"
description: "The type of information to return in the response. <br /><br\
\ /> <span class=\"tablenote\"> <strong>Important:</strong> This parameter\
\ may not produce valid results if you also provide more than one value\
\ for the <b>category_ids</b> parameter. It is recommended that you avoid\
\ using this combination. </span> <br /><br /> <b> Valid Values: </b> <ul>\
\ <li><code>ASPECT_REFINEMENTS</code> — This returns the <b>refinement</b>\
\ container, which includes the category aspect and aspect value distributions\
\ that apply to the returned products. For example, if you searched for\
\ <code>Ford Mustang</code>, some of the category aspects might be <b>Model\
\ Year</b>, <b>Exterior Color</b>, <b>Vehicle Mileage</b>, and so on. <br\
\ /> <br /> <span class=\"tablenote\"> <b>Note: </b>Aspects are category\
\ specific.</span> </li> <li><code>FULL</code> — This returns all\
\ the refinement containers and all the matching products. This value overrides\
\ the other values, which will be ignored.</li> <li><code>MATCHING_PRODUCTS</code>\
\ — This returns summaries for all products that match the values\
\ you provide for the <b>q</b> and <b>category_ids</b> parameters. This\
\ does not affect your use of the <code>ASPECT_REFINEMENTS</code> value,\
\ which you can use in the same call.</li> </ul> Code so that your app gracefully\
\ handles any future changes to this list. <br /><br /><b>Default: </b>\
\ <code>MATCHING_PRODUCTS</code>"
required: false
schema:
type: "string"
- name: "gtin"
in: "query"
description: "A string consisting of one or more comma-separated Global Trade\
\ Item Numbers (GTINs) that identify products to search for. Currently the\
\ GTIN values can include EAN, ISBN, and UPC identifier types. <br /><br\
\ /> <span class=\"tablenote\"> <strong>Note:</strong> Although all query\
\ parameters are optional, this method must include at least the <b>q</b>\
\ parameter, or the <b>category_ids</b>, <b>gtin</b>, or <b>mpn</b> parameter\
\ with a valid value. <br /><br /> You cannot use the <b>gtin</b> parameter\
\ in the same method with either the <b>q</b> parameter or the <b>aspect_filter</b>\
\ parameter. </span>"
required: false
schema:
type: "string"
- name: "limit"
in: "query"
description: "The number of product summaries to return. This is the <i>result\
\ set</i>, a subset of the full collection of products that match the search\
\ or filter criteria of this call. <br /><br /> <b>Maximum:</b> <code>200</code>\
\ <br /> <b>Default:</b> <code>50</code>"
required: false
schema:
type: "string"
- name: "mpn"
in: "query"
description: "A string consisting of one or more comma-separated Manufacturer\
\ Part Numbers (MPNs) that identify products to search for. This method\
\ will return all products that have one of the specified MPNs. <br /><br\
\ /> MPNs are defined by manufacturers for their own products, and are therefore\
\ certain to be unique only within a given brand. However, many MPNs do\
\ turn out to be globally unique. <br /><br /> <span class=\"tablenote\"\
> <strong>Note:</strong> Although all query parameters are optional, this\
\ method must include at least the <b>q</b> parameter, or the <b>category_ids</b>,\
\ <b>gtin</b>, or <b>mpn</b> parameter with a valid value. <br /><br />\
\ You cannot use the <b>mpn</b> parameter in the same method with either\
\ the <b>q</b> parameter or the <b>aspect_filter</b> parameter. </span>"
required: false
schema:
type: "string"
- name: "offset"
in: "query"
description: "This parameter is reserved for internal or future use."
required: false
schema:
type: "string"
- name: "q"
in: "query"
description: "A string consisting of one or more keywords to use to search\
\ for products in the eBay catalog. <br /><br /> <span class=\"tablenote\"\
> <strong>Note:</strong> This method searches the following product record\
\ fields: <b>title</b>, <b>description</b>, <b>brand</b>, and <b>aspects.localizedName</b>,\
\ which do not include product IDs. Wildcard characters (e.g. <code>*</code>)\
\ are not allowed. </span> <br /><br /> The keywords are handled as follows:\
\ <ul> <li>If the keywords are separated by a comma (e.g. <code>iPhone,256GB</code>),\
\ the query returns products that have <code>iPhone</code> <b>AND</b> <code>256GB</code>.</li>\
\ <li>If the keywords are separated by a space (e.g. <code>\"iPhone ipad\"\
</code> or <code>\"iPhone, ipad\"</code>), the query ignores any commas\
\ and returns products that have <code>iPhone</code> <b>OR</b> <code>iPad</code>.</li>\
\ </ul> <span class=\"tablenote\"> <strong>Note:</strong> Although all query\
\ parameters are optional, this method must include at least the <b>q</b>\
\ parameter, or the <b>category_ids</b>, <b>gtin</b>, or <b>mpn</b> parameter\
\ with a valid value. <br /><br /> You cannot use the <b>q</b> parameter\
\ in the same method with either the <b>gtin</b> parameter or the <b>mpn</b>\
\ parameter. </span>"
required: false
schema:
type: "string"
responses:
200:
description: "Success"
content:
application/json:
schema:
$ref: "#/components/schemas/ProductSearchResponse"
400:
description: "Bad Request"
x-response-codes:
errors:
75008:
domain: "API_CATALOG"
category: "REQUEST"
description: "The 'fieldgroups' value {fieldgroups} is invalid. The\
\ supported fieldgroups are: {supportedFieldgroups}"
75013:
domain: "API_CATALOG"
category: "REQUEST"
description: "The 'aspect_filter' query parameter must include a categoryId.\
\ For more information, see the API call reference documentation."
75012:
domain: "API_CATALOG"
category: "REQUEST"
description: "The aspect_filter format is invalid. For more information,\
\ see the API call reference documentation."
75015:
domain: "API_CATALOG"
category: "REQUEST"
description: "Insufficient permissions to fulfill the request."
75014:
domain: "API_CATALOG"
category: "REQUEST"
description: "The categoryId in 'aspect_filter' query parameter is\
\ invalid. For more information, see the API call reference documentation."
75001:
domain: "API_CATALOG"
category: "REQUEST"
description: "The call must have a valid 'q', or 'category_ids' or\
\ 'gtin' or 'mpn' query parameter."
75017:
domain: "API_CATALOG"
category: "REQUEST"
description: "The specified GTIN value is invalid."
75019:
domain: "API_CATALOG"
category: "REQUEST"
description: "The call with 'gtin/mpn' cannot be made with aspect_filter."
75018:
domain: "API_CATALOG"
category: "REQUEST"
description: "The call must be made with either 'q' or 'gtin/mpn'."
75004:
domain: "API_CATALOG"
category: "REQUEST"
description: "The 'limit' value should be between 1 and 200 (inclusive)."
75007:
domain: "API_CATALOG"
category: "REQUEST"
description: "Currently, the {marketplaceId} marketplace is not supported.\
\ The supported Marketplaces are: {allowedMarketplaces} ."
75006:
domain: "API_CATALOG"
category: "REQUEST"
description: "Top level category browsing is not allowed. Please provide\
\ keywords or more filters for the applied top level category."
500:
description: "Internal Server Error"
x-response-codes:
errors:
75000:
domain: "API_CATALOG"
category: "APPLICATION"
description: "There was a problem with an eBay internal system or\
\ process. Contact eBay developer support for assistance."
204:
description: "No Content"
403:
description: "Forbidden"
security:
- api_auth:
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- "https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly"
components:
schemas:
Aspect:
type: "object"
properties:
localizedName:
type: "string"
description: "The localized name of this category aspect."
localizedValues:
type: "array"
description: "A list of the localized values of this category aspect."
items:
type: "string"
description: "This type contains the name and values of a category aspect."
AspectDistribution:
type: "object"
properties:
aspectValueDistributions:
type: "array"
description: "Contains information about one or more values of the category\
\ aspect identified by <b>localizedAspectName</b>. "
items:
$ref: "#/components/schemas/AspectValueDistribution"
localizedAspectName:
type: "string"
description: "The localized name of an aspect that is associated with the\
\ category identified by <b>dominantCategoryId</b>."
description: "This type contains information about one category aspect that\
\ is associated with a specified category."
AspectValueDistribution:
type: "object"
properties:
localizedAspectValue:
type: "string"
description: "The localized value of the category aspect identified by <b>refinement.aspectDistributions.localizedAspectName</b>."
matchCount:
type: "integer"
description: "The number of times the value of <b>localizedAspectValue</b>\
\ has been used for eBay product listings. By comparing this quantity\
\ to the <b>matchCount</b> for other values of the same aspect, you can\
\ present a histogram of the values to sellers, who can use that information\
\ to select which aspect value is most appropriate for their product.\
\ You can then include the user-selected value in the the <b>search</b>\
\ call's <b>aspect_filter</b> parameter to refine your search."
format: "int32"
refinementHref:
type: "string"
description: "A HATEOAS reference that further refines the search with this\
\ particular <b>localizedAspectValue</b>."
description: "This type contains information about one value of a specified\
\ aspect. This value serves as a product refinement."
Error:
type: "object"
properties:
category:
type: "string"
description: "Identifies the type of erro."
domain:
type: "string"
description: "Name for the primary system where the error occurred. This\
\ is relevant for application errors."
errorId:
type: "integer"
description: "A unique number to identify the error."
format: "int32"
inputRefIds:
type: "array"
description: "An array of request elements most closely associated to the\
\ error."
items:
type: "string"
longMessage:
type: "string"
description: "A more detailed explanation of the error."
message:
type: "string"
description: "Information on how to correct the problem, in the end user's\
\ terms and language where applicable."
outputRefIds:
type: "array"
description: "An array of request elements most closely associated to the\
\ error."
items:
type: "string"
parameters:
type: "array"
description: "An array of name/value pairs that describe details the error\
\ condition. These are useful when multiple errors are returned."
items:
$ref: "#/components/schemas/ErrorParameter"
subdomain:
type: "string"
description: "Further helps indicate which subsystem the error is coming\
\ from. System subcategories include: Initialization, Serialization, Security,\
\ Monitoring, Rate Limiting, etc."
description: "This type defines the fields that can be returned in an error."
ErrorParameter:
type: "object"
properties:
name:
type: "string"
description: "The object of the error."
value:
type: "string"
description: "The value of the object."
Image:
type: "object"
properties:
height:
type: "integer"
description: "The height of the image in pixels."
format: "int32"
imageUrl:
type: "string"
description: "The eBay Picture Services (EPS) URL of the image."
width:
type: "integer"
description: "The width of the image in pixels."
format: "int32"
description: "This type contains information about a product image stored in\
\ eBay Picture Services (EPS)."
Product:
type: "object"
properties:
additionalImages:
type: "array"
description: "Contains information about additional images associated with\
\ this product. For the primary image, see the <b>image</b> container."
items:
$ref: "#/components/schemas/Image"
aspects:
type: "array"
description: "Contains an array of the category aspects and their values\
\ that are associated with this product."
items:
$ref: "#/components/schemas/Aspect"
brand:
type: "string"
description: "The manufacturer's brand name for this product."
description:
type: "string"
description: "The rich description of this product, which might contain\
\ HTML."
ean:
type: "array"
description: "A list of all European Article Numbers (EANs) that identify\
\ this product."
items:
type: "string"
epid:
type: "string"
description: "The eBay product ID of this product."
gtin:
type: "array"
description: "A list of all GTINs that identify this product. Currently\
\ this can include EAN, ISBN, and UPC identifier types."
items:
type: "string"
image:
description: "Contains information about the primary image of this product.\
\ For more images of this product, see the <b>additionalImages</b> container."
$ref: "#/components/schemas/Image"
isbn:
type: "array"
description: "A list of all International Standard Book Numbers (ISBNs)\
\ that identify this product. "
items:
type: "string"
mpn:
type: "array"
description: "A list of all MPN values that the manufacturer uses to identify\
\ this product."
items:
type: "string"
otherApplicableCategoryIds:
type: "array"
description: "A list of category IDs (other than the value of <b>primaryCategoryId</b>)\
\ for all the leaf categories to which this product might belong."
items:
type: "string"
primaryCategoryId:
type: "string"
description: "The identifier of the leaf category that eBay recommends using\
\ to list this product, based on previous listings of similar products.\
\ Products in the eBay catalog are not automatically associated with any\
\ particular category, but using an inappropriate category can make it\
\ difficult for prospective buyers to find the product. For other possible\
\ categories that might be used, see <b>otherApplicableCategoryIds</b>."
productWebUrl:
type: "string"
description: "The URL for this product's eBay product page."
title:
type: "string"
description: "The title of this product on eBay."
upc:
type: "array"
description: "A list of Universal Product Codes (UPCs) that identify this\
\ product."
items:
type: "string"
version:
type: "string"
description: "The current version number of this product record in the catalog."
description: "This type contains the full details of a specified product, including\
\ information about the product's identifiers, product images, aspects, and\
\ categories."
ProductSearchResponse:
type: "object"
properties:
href:
type: "string"
description: "This field is reserved for internal or future use. <!-- The\
\ URI of the <b>search</b> method request that produced this result set.\
\ -->"
limit:
type: "integer"
description: "The number of product summaries returned in the response.\
\ This is the <i>result set</i>, a subset of the full collection of products\
\ that match the search or filter criteria of this call. If the <b>limit</b>\
\ query parameter was included in the request, this field will have the\
\ same value. <br /><br /> <b>Default:</b> <code>50</code>"
format: "int32"
next:
type: "string"
description: "This field is reserved for internal or future use. <!-- <i>Returned\
\ only if</i> there are more product records to retrieve from the current\
\ collection of matching products, this field contains the <b>search</b>\
\ call URI for the next result set. For example, the following URI returns\
\ records 41 thru 50 from the collection of matched products: <br /><br\
\ /> <code><i>path</i>/product_summary/search?limit=10&offset=40</code>\
\ <br /><br /> <span class=\"tablenote\"><strong>Note:</strong> This\
\ feature employs a zero-based list, where the first product in the list\
\ has an offset of <code>0</code>.</span> -->"
offset:
type: "integer"
description: "This field is reserved for internal or future use. <!-- The\
\ distance (number of records) from the first product in the collection\
\ to the first product in this result set. If the <b>offset</b> query\
\ parameter was included in the request, this field will have the same\
\ value. The <b>offset</b> value is used in conjunction with the <b>limit</b>\
\ value to control the pagination of the output. For example, if <b>offset</b>\
\ is set to <code>30</code> and <b>limit</b> is set to <code>10</code>,\
\ the call retrieves products 31 thru 40 from the resulting collection\
\ of products. <br /><br /> <span class=\"tablenote\"><strong>Note:</strong>\
\ This feature employs a zero-based list, where the first item in the\
\ list has an offset of <code>0</code>.</span> <br /><br /> <b>Default:</b>\
\ <code>0</code> (zero) -->"
format: "int32"
prev:
type: "string"
description: "This field is reserved for internal or future use. !-- <i>Not\
\ returned if</i> the currently returned result set is the first set of\
\ product records from the current collection of matching products. This\
\ field contains the <b>search</b> call URI for the previous result set.\
\ For example, the following URI returns products 21 thru 30 from the\
\ collection of products: <br /><br /> <code><i>path</i>/product_summary/search?limit=10&offset=20</code>\
\ <br /><br /> <span class=\"tablenote\"><strong>Note:</strong> This\
\ feature employs a zero-based list, where the first product in the list\
\ has an offset of <code>0</code>.</span> >"
productSummaries:
type: "array"
description: "<i>Returned if</i> the <b>fieldGroups</b> query parameter\
\ was omitted from the request, or if it was included with a value of\
\ <code>MATCHING_PRODUCTS</code> or <code>FULL</code>. This container\
\ provides an array of product summaries in the current result set for\
\ products that match the combination of the <b>q</b>, <b>category_ids</b>,\
\ and <b>aspect_filter</b> parameters that were provided in the request.\
\ Each product summary includes information about the product's identifiers,\
\ product images, aspects, the product page URL, and the <b>getProduct</b>\
\ URL for retrieving the product details."
items:
$ref: "#/components/schemas/ProductSummary"
refinement:
description: "<i>Returned only if</i> the <b>fieldGroups</b> query parameter\
\ was included in the request with a value of <code>ASPECT_REFINEMENTS</code>\
\ or <code>FULL</code>. <br /><br /> An aspect is a property of a category,\
\ used by sellers to provide details about the items they're listing.\
\ For example, the <i>Cell Phones & Smartphones</i> category (#9355)\
\ includes a <i>Storage Capacity</i> aspect. <br /><br /> This container\
\ provides information about the distribution of values of a set of category\
\ aspects. The category aspects are those associated with the category\
\ that eBay determines is most likely to cover the products that match\
\ the search criteria."
$ref: "#/components/schemas/Refinement"
total:
type: "integer"
description: "This field is reserved for internal or future use. <!-- The\
\ total number of product records in the returned collection of matched\
\ products. >"
format: "int32"
description: "This type contains the specifications for the collection of products\
\ that match the search or filter criteria of a <b>search</b> call. A maximum\
\ of 200 product summaries is returned (the result set), fewer if you include\
\ the <b>limit</b> query parameter in the request. "
ProductSummary:
type: "object"
properties:
additionalImages:
type: "array"
description: "Contains information about additional images associated with\
\ this product. For the primary image, see the <b>image</b> container."
items:
$ref: "#/components/schemas/Image"
aspects:
type: "array"
description: "Contains an array of the category aspects and their values\
\ that are associated with this product."
items:
$ref: "#/components/schemas/Aspect"
brand:
type: "string"
description: "The manufacturer's brand name for this product."
ean:
type: "array"
description: "A list of all European Article Numbers (EANs) that identify\
\ this product."
items:
type: "string"
epid:
type: "string"
description: "The eBay product ID of this product."
gtin:
type: "array"
description: "A list of all GTINs that identify this product. This includes\
\ all of the values returned in the <b>ean</b>, <b>isbn</b>, and <b>upc</b>\
\ fields."
items:
type: "string"
image:
description: "Contains information about the primary image of this product.\
\ For more images of this product, see the <b>additionalImages</b> container."
$ref: "#/components/schemas/Image"
isbn:
type: "array"
description: "A list of all International Standard Book Numbers (ISBNs)\
\ that identify this product."
items:
type: "string"
mpn:
type: "array"
description: "A list of all Manufacturer Product Number (MPN) values that\
\ the manufacturer uses to identify this product."
items:
type: "string"
productHref:
type: "string"
description: "The URI of the <b>getProduct</b> call request that retrieves\
\ this product's details."
productWebUrl:
type: "string"
description: "The URL for this product's eBay product page."
title:
type: "string"
description: "The title of this product on eBay."
upc:
type: "array"
description: "A list of Universal Product Codes (UPCs) that identify this\
\ product."
items:
type: "string"
description: "This type contains a summary of a specified product. The product\
\ summary includes information about the product's identifiers, product images,\
\ aspects, and the <b>getProduct</b> URL for retrieving the product details."
Refinement:
type: "object"
properties:
aspectDistributions:
type: "array"
description: "Contains information about one or more aspects that are associated\
\ with the category identified by <b>dominantCategoryId</b>."
items:
$ref: "#/components/schemas/AspectDistribution"
dominantCategoryId:
type: "string"
description: "The ID of the category that eBay determines is most likely\
\ to cover the products matching the search criteria."
description: "This type identifies a product category and the aspects associated\
\ with that category. Each aspect distribution container returns the distribution\
\ of values that have been used for the aspect."
securitySchemes:
api_auth:
type: "oauth2"
description: "The security definitions for this API. Please check individual\
\ operations for applicable scopes."
flows:
authorizationCode:
authorizationUrl: "https://auth.ebay.com/oauth2/authorize"
tokenUrl: "https://api.ebay.com/identity/v1/oauth2/token"
scopes:
https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly: " This\
\ scope would allow signed in user to read catalog data."
https://api.ebay.com/oauth/api_scope/sell.inventory: "View and manage\
\ your inventory and offers"