eBay continues to work towards establishing the most comprehensive catalog of product and product aspect information in commerce. By using eBay catalog information and required/recommended product aspects to create listings, sellers will be more likely to create accurate listings that are easily found by buyers using commonly-used search terms for the particular product. Sellers can still customize listing descriptions, provide their own photos, and add item specifics that are unique to their own items.
You can use the Catalog API to assist sellers in finding the products in the eBay catalog that correspond to items the sellers want to offer for sale. When corresponding products are found for seller items, the product information will be used to populate the item listings, and sellers won't have to enter those product details themselves. This automates and dramatically speeds up the process of creating offers, and makes items easier for buyers to discover. You can also use the Catalog API to find product aspect metadata that is unique to one or eBay categories.
Each product (or product variation) in the eBay catalog is uniquely identified by an eBay product ID (ePID), and possibly a brand and manufacturer part number (MPN), or a Global Trade Item Number (GTIN) such as a UPC, EAN, or ISBN. Other unique identifiers will be recognized in the future.
With the Catalog API, you can find a product that matches the seller's information about an item using category IDs, keywords, product attributes, and aspect refinements, enable the seller to confirm the matching product, and retrieve the product's ePID to use to list the item. eBay will include all of the product information from the catalog in the seller's listing.
Primary Catalog API objects
Objects are as follows:
- Product Summary
The ProductSummary object contains basic information about a product, including the product's title, aspects and their values, associated images, and any recognized identifiers that apply to the product. It also includes a URL to its eBay Product page.
The Refinement object contains the aspects (properties) of a specified eBay category, along with the values that have been used for each aspect, and a count of the number of times that each value has been used in previous eBay listings. This information is used to help sellers choose the most appropriate search criteria for the product.
The Product object contains detailed information about a product, including the product's title and description, aspects and their values, associated images, applicable category IDs, and any recognized identifiers that apply to the product.
- Product Aspect
The ProductAspect object contains information about a type of product attribute (an aspect)that varies according to a product's brand and category. For example, an aspect called Sleeve Length may apply to shirts, but not to cameras. Every combination of product brand and category can have a unique combination of aspects.
- Product Metadata
The ProductMetadata object contains the typical product aspects and product identifiers that are required or highly recommended for eBay Catalog products in specific eBay categories. The getProductMetadata and/or getProductMetadataForCategories calls should be made before make a catalog change request to add a new product to the eBay Catalog or to make a request to modify an existing eBay Catalog product.
- Change Request
Note: The three catalog change request methods in the Catalog API are deprecated, and are scheduled to be decommissioned in Q1 of 2020. See the latest Release Notes for more information about deprecation of the change request methods.
The ChangeRequest object contains detailed information about a seller's request that eBay update an existing product or create a new product that will successfully match the seller's inventory item. This object also includes information about corrections to the suggested product, existing products that conflict with the suggested product, and violations of eBay standards in the values of the suggested product's aspects or fixed attributes.
Business use cases
This section outlines the high-level use cases addressed by the Catalog API.
Discover catalog products on which to base an eBay listing
Before creating an eBay listing for an item, use the search call to discover the correct catalog product on which to base the listing.
You can request refinement data, which includes histogram information for all aspects of a category that eBay recommends or that you specify. Present the histogram data to the seller to select aspect values that match their items, then use those values to filter the search results.
You can narrow your choices by identifying one or more categories for the product, and keywords to search for in the product records, which will return candidate product summaries to present to the seller for confirmation.
Retrieve the details of a product
If a seller could not confirm a matching product for their item based on product summaries, use the getProduct call to retrieve all available details about individual catalog products, and present those details to the seller to select a matching product.
Retrieve the required/recommended aspects and identifiers for a catalog product
Use the getProductMetadata and/or getProductMetadataForCategories calls to retrieve required and recommended product aspects and identifiers based on the product and on the eBay listing category.
Update an existing product
Note: The three catalog change request methods in the Catalog API are deprecated, and are scheduled to be decommissioned in Q1 of 2020. Updating an existing product with the createChangeRequest method is no longer supported for any eBay categories and will only return an error if used.
Sellers may find that no existing product exactly matches an inventory item for a variety of reasons. For a given catalog product, you can use the createChangeRequest call to request a change to add to the valid values of an aspect (such as a new color), create a new aspect (such as Monogram), or correct an existing aspect value (such as a typographical error).
Create a new product
Note: The three catalog change request methods in the Catalog API are deprecated, and are scheduled to be decommissioned in Q1 of 2020. Creating a new catalog product with the createChangeRequest method is no longer supported for any eBay categories and will only return an error if used.
If all of the existing catalog products of a given brand and category are valid, but none match a seller's inventory item, you can use the createChangeRequest call to request the creation of a new product by specifying all of the fixed attributes and the aspects needed to define the product.
Manage your change requests
Note: The three catalog change request methods in the Catalog API are deprecated, and are scheduled to be decommissioned in Q1 of 2020. Currently, the getChangeRequest or getChangeRequests methods may still return data if any change requests exist for the user, but the data will be static, the status of change requests will not change, and it will not be possible to make any changes to any change requests. At any time, it is possible that all catalog change requests for a user will be removed, and then these methods will either trigger an error or just return an empty array.
The process of eBay reviewing and resolving catalog change requests may take up to an hour, and sometimes longer. Use the getChangeRequest and getChangeRequests calls to find, retrieve, and monitor the status of your submitted change requests.
Currently the Catalog API is supported in the US, GB, AU, and CA (en) marketplaces.
Support for parts compatibility
The Catalog API is now the primary tool for retrieving product information from the eBay catalog, but it does not support eBay Parts Compatibility (fitment). See instead the Product Services APIs, which now support only Parts Compatibility.
Sandbox vs. Production data
The data in the eBay Sandbox environment is static. It can be limited in scope and quantity, and is sometimes simulated or mock data. As a result, you should not depend on data in the Production environment to have the same limitations. Use good coding practices to anticipate the wider range and variability of data that your application is likely to encounter.
The Catalog API limits the number of calls that can be made per day on behalf of your application. For the current application rate limits, see the eBay API Call Limits page.
The Catalog API also limits the number of calls that can be made by the authenticated user. Calls made on behalf of a given user are limited to 100,000 calls/day.