Pre-filling Item Specifics with Product Details

A catalog product) is a predefined product description from a catalog. Catalog products are available for a wide variety of products, such as smart phones, tablets, home applicances, TVs, sporting goods, and more.

Buyers are more likely to buy if they can see complete, organized product information. Including details from our product catalog in your listings creates a shopping experience that speeds the buyer's path from search to purchase.

Listing your item with product details from our catalog

To buyers, product details are shown in eBay's View Item page, and in similar pages in eBay Mobile apps, as shown below.

Product Details
 Figure: Product Details in eBay's View Item Page

The API supports two main workflows for listing with product details:

If you use a standard identifier like UPC, eBay will attempt to find a matching product for you, to use in your listing. If a single matching product is found, the item will be listed with that catalog product's details, including the product's title, description, items specifics, and stock photo. If you also set ProductListingDetails.UseStockPhotoURLAsGallery as true, the stock photo will be used as the gallery image.

If more than one match is found, eBay returns an error indicating that too many products were found, along with a list of possible product IDs for the products. In this case, either choose one of those IDs, or use FindProducts in the Shopping API to search for the right product, and use its EPID instead (an EPID is always unique).

It is also possible to list with a value called ProductID in the API. This is a versioned form of the EPID, and it is less commonly used. However, it may be returned as an option when you use a standard identifier like ISBN, and multiple matching products are found. If you pass in an old product ID that eBay still recognizes and only one match is found, eBay will list the item with the latest version of the product and the latest product ID, and the call will return a warning indicating that the data has changed.

You do not need to specify a PrimaryCategory.CategoryID if you are able to match your item to a catalog product using the ProductListingDetails container. eBay will automatically list the item in the appropriate category based on the category product. In some cases, your item may be listed in more than one category. However, if you specify the category in the PrimaryCategory.CategoryID, your specified category takes precedence whether a matching catalog product is found or not.

ProductID Error Handling

In rare cases, if you pass in an old product ID in ProductID (or possibly an old EPID), and eBay has mapped the value to a new product ID in the eBay system, you may receive an error or warning that the product ID was updated. If you encounter this issue, you may be able to control how this error is processed by using the ErrorHandling field in your request.

Note: eBay makes an effort to minimize such changes to product IDs. Please also note that if you specify a product ID that eBay does not recognize (including a very old product ID that is not mapped to a current product ID in the system), this is treated as a "product not found" error (12024) instead. eBay's response to this error condition is not affected by the error handling preference you specify.

Error Messages

Either warning 5119 or error 5123 will be returned, depending on the preference you specify. These are user-facing messages.

Error Handling Preference Effects

The table below shows how eBay handles this scenario based on the error preference you pass in the listing request.

Catalog Product ID Updated

BestEffort AllOrNone FailOnError Legacy
Severity Warning (5119) Warning (5119) Error (5123) Warning (5123)
Listing effect List the item List the item Reject the listing. List the item.

Common Causes