---
swagger: "2.0"
info:
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."
version: "v1_beta.5.0"
title: "Catalog API"
contact:
name: "eBay Inc,"
license:
name: "eBay API License Agreement"
url: "https://go.developer.ebay.com/api-license-agreement"
host: "api.ebay.com"
basePath: "/commerce/catalog/v1_beta"
schemes:
- "https"
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.
For a new listing, you can use the search\
\ method to identify candidate products on which to base the listing, then\
\ use the getProduct method to present the full details of those candidate\
\ products to the seller to make a a final selection."
operationId: "getProduct"
produces:
- "application/json"
parameters:
- name: "X-EBAY-C-MARKETPLACE-ID"
in: "header"
description: "This method also uses the X-EBAY-C-MARKETPLACE-ID
\
\ header to identify the seller's eBay marketplace. It is required for all\
\ marketplaces except EBAY_US, which is the default. Note: This method\
\ is limited to EBAY_US
, EBAY_AU
, EBAY_CA
,\
\ and EBAY_GB
values."
required: false
type: "string"
- name: "epid"
in: "path"
description: "The ePID of the product being requested. This value can be discovered\
\ by issuing the search method and examining the value of the productSummaries.epid\
\ field for the desired returned product summary."
required: true
type: "string"
responses:
200:
description: "OK"
schema:
$ref: "#/definitions/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:
- Authorization Code:
- "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 search include keywords, product categories,\
\ and category aspects. To see the full details of a selected product, use\
\ the getProduct call.
In addition to product summaries,\
\ this method can also be used to identify refinements, which help\
\ you to better pinpoint the product you're looking for. A refinement consists\
\ of one or more aspect 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 refinement container is returned\
\ when you include the fieldGroups query parameter in the request with\
\ a value of ASPECT_REFINEMENTS
or FULL
.
Example
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 Silver
, Brushed Nickel
, Pewter
,\
\ or even Grey
. The returned refinement 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 search method again with those values in the aspect_filter\
\ parameter to narrow down the collection of products returned by the call.\
\
Although all query parameters are optional, this method must\
\ include at least the q parameter, or the category_ids, gtin,\
\ or mpn 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.
Note: This method requires that certain\
\ special characters in the query parameters be percent-encoded:
(space)
= %20
,
\
\ = %2C
:
=\
\ %3A
[
= %5B
\
\ ]
= %5D
{
\
\ = %7B
|
=\
\ %7C
}
= %7D
\
\
This requirement applies to all query parameter values. However,\
\ for readability, method examples and samples in this documentation will\
\ not use the encoding.
This method returns product summaries\
\ rather than the full details of the products. To retrieve the full details\
\ of a product, use the getProduct method with an ePID."
operationId: "search"
produces:
- "application/json"
parameters:
- name: "X-EBAY-C-MARKETPLACE-ID"
in: "header"
description: "This method also uses the X-EBAY-C-MARKETPLACE-ID
\
\ header to identify the seller's eBay marketplace. It is required for all\
\ marketplaces except EBAY_US, which is the default. Note: This method\
\ is limited to EBAY_US
, EBAY_AU
, EBAY_CA
,\
\ and EBAY_GB
values."
required: false
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.
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.\
\
You can determine appropriate values for the aspects by first\
\ submitting this method without this parameter. It will return either the\
\ productSummaries.aspects container, the refinement.aspectDistributions\
\ container, or both, depending on the value of the fieldgroups parameter\
\ in the request. The productSummaries.aspects container provides\
\ the category aspects and their values that are associated with each returned\
\ product. The refinement.aspectDistributions 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.
Note: You can also use\
\ the Taxonomy API's getItemAspectsForCategory method to retrieve\
\ detailed information about aspects and their values that are appropriate\
\ for your selected category.
The syntax for the aspect_filter\
\ parameter is as follows (on several lines for readability; categoryId\
\ is required):
aspect_filter=categoryId:category_id,
\
\
aspect1:{valueA|valueB|...},
aspect2:{valueC|valueD|...},.
A matching product must be within the specified category,\
\ and it must have least one of the values identified for every specified\
\ aspect.
Note:\
\ Aspect names and values are case sensitive.
Here\
\ is an example of an aspect_filter parameter in which 9355
\
\ is the category ID, Color
is an aspect of that category,\
\ and Black
and White
are possible values of that\
\ aspect (on several lines for readability):
GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?
aspect_filter=categoryId:9355,Color:{White|Black}
Here is the aspect_filter with required URL encoding and a second\
\ aspect (on several lines for readability):
GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?
\
\
aspect_filter=categoryId:9355,Color:%7BWhite%7CBlack%7D,
Storage%20Capacity:%128GB%7C256GB%7D
Note: You cannot\
\ use the aspect_filter parameter in the same method with either\
\ the gtin parameter or the mpn parameter. For implementation\
\ help, refer to eBay API documentation at https://developer.ebay.com/api-docs/commerce/catalog/types/catal:AspectFilter"
required: false
type: "string"
- name: "category_ids"
in: "query"
description: " Important: Currently,\
\ only the first category_id value is accepted.
One or more comma-separated category identifiers for narrowing down\
\ the collection of products returned by this call.
Note: This parameter requires a valid category\
\ ID value. You can use the Taxonomy API's getCategorySuggestions\
\ method to retrieve appropriate category IDs for your product based on\
\ keywords.
The syntax for this parameter is as follows:\
\
category_ids=category_id1,category_id2,.
\
\
Here is an example of a method with the category_ids\
\ parameter: br />
GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?
category_ids=178893
\
\ Note: Although all query parameters are optional, this\
\ method must include at least the q parameter, or the category_ids,\
\ gtin, or mpn parameter with a valid value.
\
\ If you provide only the category_ids parameter, you cannot specify\
\ a top-level (L1) category. "
required: false
type: "string"
- name: "fieldgroups"
in: "query"
description: "The type of information to return in the response.
Important: This parameter\
\ may not produce valid results if you also provide more than one value\
\ for the category_ids parameter. It is recommended that you avoid\
\ using this combination.
Valid Values:
ASPECT_REFINEMENTS
— This returns the refinement\
\ container, which includes the category aspect and aspect value distributions\
\ that apply to the returned products. For example, if you searched for\
\ Ford Mustang
, some of the category aspects might be Model\
\ Year, Exterior Color, Vehicle Mileage, and so on. FULL
— This returns all\
\ the refinement containers and all the matching products. This value overrides\
\ the other values, which will be ignored.MATCHING_PRODUCTS
\
\ — This returns summaries for all products that match the values\
\ you provide for the q and category_ids parameters. This\
\ does not affect your use of the ASPECT_REFINEMENTS
value,\
\ which you can use in the same call.MATCHING_PRODUCTS
"
required: false
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. 200
\
\ 50
"
required: false
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. *
)\
\ are not allowed. iPhone,256GB
),\
\ the query returns products that have iPhone
AND 256GB
.\"iPhone ipad\"\
or \"iPhone, ipad\"
), the query ignores any commas\
\ and returns products that have iPhone
OR iPad
.50
"
next:
type: "string"
description: "This field is reserved for internal or future use. "
offset:
type: "integer"
description: "This field is reserved for internal or future use. "
prev:
type: "string"
description: "This field is reserved for internal or future use. !-- Not\
\ returned if the currently returned result set is the first set of\
\ product records from the current collection of matching products. This\
\ field contains the search call URI for the previous result set.\
\ For example, the following URI returns products 21 thru 30 from the collection\
\ of products: path/product_summary/search?limit=10&offset=20
\
\ 0
. >"
productSummaries:
type: "array"
description: "Returned if the fieldGroups query parameter was\
\ omitted from the request, or if it was included with a value of MATCHING_PRODUCTS
\
\ or FULL
. This container provides an array of product summaries\
\ in the current result set for products that match the combination of the\
\ q, category_ids, and aspect_filter 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 getProduct URL for retrieving the product details."
items:
$ref: "#/definitions/ProductSummary"
refinement:
$ref: "#/definitions/Refinement"
total:
type: "integer"
description: "This field is reserved for internal or future use.