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. Buyers are then able to compare 'apples to apples', and base their purchasing decisions on real differences between listings, such as price, shipping cost, and any item promotions.
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.
For more information about finding eBay catalog products and using these products to list, see Matching inventory to catalog products in the Selling Integration Guide.
Technical overview
Each product (or product variation) in the eBay product catalog is uniquely identified by an eBay product ID (ePID), and each catalog product is generally associated with one or more Global Trade Item Numbers (GTINs), such as a UPC, EAN, or ISBN, or possibly a manufacturer part number (MPN), which is always pair with a product brand.
With the Catalog API, you can search for a matching catalog product using category IDs, keywords, product attributes, and aspect refinements. Once the seller is able to confirm that a catalog product is a match, that seller will grab the product's epid value, and use this value to create a listing based on the catalog product's details. 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.
- Refinement
-
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.
- 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.
Business use cases
This section outlines the high-level use cases addressed by the Catalog API.
Discover candidate 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 products, and present those details to the seller to select a matching product.
API restrictions
Supported marketplaces
The Catalog API is supported in the AU, CA (en), DE, ES, FR, GB, IT, and US marketplaces.
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.
Rate limits
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 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.