catalog APIv1_beta.3.0

Catalog API Overview

eBay continues to work towards establishing the most comprehensive catalog of product information in commerce. eBay's goal is to optimize the Product-Based Shopping Experience and to help insure that all listings based off of catalog data have complete and accurate information as possible.

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, possibly 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 complementary 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.

The Catalog API can be used to find the products in the eBay catalog that correspond to items that sellers want to offer for sale. Once a matching catalog product is found, the seller provides the catalog product identifier at listing/revision time, and the product information defined in the catalog product is used to populate the listing, including listing title, listing description, product aspects, and any stock photo(s). Sellers will not have to enter product aspects (aka item specifics) themselves, unless there are one or more item specifics that are unique to that specific item. 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 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

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.

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.