Pre-filling Item Specifics with Product Details
A product (or catalog product) is a predefined (stock) item description from a catalog. Product information is available for a wide variety of products, such as cameras, books, DVDs, sporting equipment, tickets to well-known events and venues, and more.
Buyers are more likely to buy if they can see key product information immediately. 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.
Figure: Product Details in eBay's View Item Page
The API supports two main workflows for listing with product details:
- Specify industry-standard identifiers:
For most sellers, the fastest way to list with product details is to pass in an industry-standard identifier, such as ISBN, UPC, GTIN, EAN, or Brand+MPN in ProductListingDetails in AddItem or related calls.
Similarly, you can list event tickets by specifying a few well-known details in ProductListingDetails, such as the event name and other data, supplemented by custom item specifics. See Ticket Listings for more information on listing tickets.
With this approach, eBay searches its product catalog for a product that matches the ID you passed in, and (if a match is found) uses that product in the listing.
- Search the product catalog for an eBay Product ID (EPID)
With this approach, you use FindProducts in the Shopping API to search for the right product, and look at it's ProductReferenceID (the EPID).
Or you find a similar item on eBay that was listed with product details, and use GetItem to retrieve the item's ProductReferenceID.
In either case, once you have the EPID, you pass it in ProductListingDetails in AddItem or related calls.
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 product's stock details, including the product's stock photo and other stock information. If you also set PictureDetails.GalleryType, 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 PrimaryCategory with ProductListingDetails, because eBay can determine the category based on the product ID. However, if you specify the category, then PrimaryCategory takes precedence.
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.
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.
Table: Catalog Product ID Updated
List the item
List the item
Reject the listing.
List the item.
- A portion of the product data (such as the Additional Information section) changes on eBay. Such a change triggers a new version of the product, which in turn causes a portion of the ID string to change.
- The seller searched for product details previously and is now using the same product ID for another listing, but the ID has changed on eBay since the original product search was performed.
- The seller is relisting an existing item and the product ID has changed on eBay since the item was originally listed.
- The application uses GetItem to download an existing item with product details and attempts to use the response data in a new listing, but the product ID has changed on eBay since the downloaded item was originally listed.
- Within the application, the seller schedules the item to be listed at a future date, but the product ID changes on eBay by the time the application submits the listing.
Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.