eBay Catalog API
The eBay Catalog API gives access to the eBay product catalog so sellers can attach items to canonical product entries when listing.
OpenAPI Specification
openapi: 3.0.0
info:
title: eBay 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 <a
href="/api-docs/commerce/catalog/overview.html#supported-marketplaces"
target="_blank">supported marketplaces</a>, except EBAY_US, which is
the default.
required: false
schema:
type: string
- name: epid
in: path
description: >-
The eBay product identifier (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:
'75007':
domain: API_CATALOG
category: REQUEST
description: >-
Currently, the {marketplaceId} marketplace is not supported.
The supported Marketplaces are: {allowedMarketplaces}.
'75010':
domain: API_CATALOG
category: REQUEST
description: The specified EPID value {epid} was not found.
'75011':
domain: API_CATALOG
category: REQUEST
description: >-
The specified EPID value {epid} no longer exists. Its new
value is {newepid}.
'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.
'403':
description: Forbidden
'404':
description: Not Found
'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.
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 <a
href="/api-docs/commerce/catalog/overview.html#supported-marketplaces"
target="_blank">supported marketplaces</a>, except EBAY_US, which is
the default.
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'
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'75001':
domain: API_CATALOG
category: REQUEST
description: >-
The call must have a valid 'q', or 'category_ids' or 'gtin' or
'mpn' query parameter.
'75004':
domain: API_CATALOG
category: REQUEST
description: The 'limit' value should be between 1 and 200 (inclusive).
'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.
'75007':
domain: API_CATALOG
category: REQUEST
description: >-
Currently, the {marketplaceId} marketplace is not supported.
The supported Marketplaces are: {allowedMarketplaces} .
'75008':
domain: API_CATALOG
category: REQUEST
description: >-
The 'fieldgroups' value {fieldgroups} is invalid. The
supported fieldgroups are: {supportedFieldgroups}
'75012':
domain: API_CATALOG
category: REQUEST
description: >-
The aspect_filter format is invalid. For more information, see
the API call reference documentation.
'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.
'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.
'75015':
domain: API_CATALOG
category: REQUEST
description: Insufficient permissions to fulfill the request.
'75017':
domain: API_CATALOG
category: REQUEST
description: The specified GTIN value is invalid.
'75018':
domain: API_CATALOG
category: REQUEST
description: The call must be made with either 'q' or 'gtin/mpn'.
'75019':
domain: API_CATALOG
category: REQUEST
description: The call with 'gtin/mpn' cannot be made with aspect_filter.
'403':
description: Forbidden
'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.
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: T
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-catalog-openapi-original.yml