catalog APIv1_beta.2.0

Catalog API

eBay continues to work towards establishing the most comprehensive catalog of product information in commerce. eBay's goal is to implement the system-wide Product-Based Shopping Experience (PBSE), in which all listings for a given item are generated from the same catalog data. Sellers will be required to match their inventory items to corresponding catalog products, the details of which eBay uses to generate their listings.

Note: Currently only a certain set of products are required to be matched, based on their brand and eBay category. For current information about which brands and categories require matching, see Categories/Brands for Phase 1 in the PBSE Playbook. This set of products is expanding steadily, so be sure to monitor the Playbook to maintain compliance with this initiative.

Another benefit of using catalog information to create listings is that sellers will be less likely to add incorrect details to their listings. Such details often conflict with the catalog information, confusing and discouraging buyers. The more sellers adopt catalog information for their listings, the more consistent and reliable their listings will be. Sellers can still add their own descriptions, photos, and item specifics to enhance their listings. Buyers are then able to compare "apples to apples," and base their purchasing decisions on real differences between listings.

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.

For more information, see Matching inventory to catalog products in the Selling Integration Guide. For more information about using RESTful APIs, see Using eBay Restful APIs.

Technical overview

The eBay catalog will eventually be a master database of all manufactured products that eBay sellers have listed or might list on eBay in the future (eBay is in the process of populating the database in phases). Each product (or product variation) in the 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 inventory 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.

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.

Change Request

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 candidate products on which to base an eBay listing

Before creating an eBay listing for an item, use the search call to assist sellers 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.

Update an existing product

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

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

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.

API restrictions

Supported marketplaces

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.

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 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.