For numerous listing categories, eBay has catalog products available. Sellers have the option of finding eBay catalog products that are exact matches for their products, and then they can create or revise item listings based on the details of the catalog product.
Overview
Each product in the eBay catalog is uniquely identified by an eBay product ID (ePID). These catalog products are usually associated with other industry standard product identifiers such as UPC, EAN, or ISBN values. Many products can also be identified through a unique Brand and manufacturer part number (MPN).
When creating a new listing for a product, or revising an existing listing, an ePID can be referenced through the product.epid field of the createOrReplaceInventoryItem call in the Inventory API. If you are using the Trading API, the ePID value is referenced through ProductListingDetails.ProductReferenceID field of the AddItem call.
A key benefit of using catalog information to create/revise 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.
Attributes and aspects
Each product in the eBay catalog include the following details:
- Product title
- Product identifier(s)
- Product description
- Product aspects (aka 'item specifics')
- Stock photo(s) (not available for every catalog product
In addition to the product details listed above, each eBay catalog product is automatically mapped to an eBay listing category (some products may be mapped to multiple categories). Each listing category has different product aspects that will be relevant for that category. For example, the item specifics of the Cell Phones category (Category ID - 9355) include the following: Brand, MPN, Model, Operating System, Network, Color, and Storage Capacity. Every cell phone in this category should have these aspects (and more), but the values defined for these aspects will vary based on the specifications of the cell phone.
Note: When your seller has multiple items that differ only in the values of a few aspects, you can use item groups to associate them so they appear as variations of a single listing (see Creating and managing inventory item groups). However, each of these items is still based on a uniquely defined catalog product with its own ePID.
Find candidate products for your item
Use the Catalog API to discover the catalog products that best match a particular inventory item. You can use the search call with a combination of query parameters including category_id, q (keywords), gtin, and mpn. These combinations are restricted as follows:
- A category_id will return all products in the specified category. It can be combined with q, or with gtin and/or mpn.
- One or more comma-separated keywords in q will return all products that contain one of those keywords in their title, description, or brand. The q parameter can be combined only with category_id.
- One or more comma-separated GTIN values in gtin will return all products that are identified by one of those GTINs .Currently the GTIN values can include EAN, ISBN, and UPC identifier formats. The gtin parameter can be combined with mpn and/or category_id.
-
One or more comma-separated MPN values in mpn will return all products that are identified by one of those MPNs, regardless of manufacturer. The mpn parameter can be combined with gtin and/or category_id.
Note: MPNs are created by manufacturers for their own products, and therefore might be unique only within a given brand. Many MPNs do turn out to be globally unique, but you should not rely on this .
The search call searches for and retrieves summaries of one or more products in the eBay catalog that match the search criteria provided. Here's an example of a search for the keyword iphone with a limit (for readability) of 1 record to return:
GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? q=iphone& limit=1
The response contains a product summary for the first iPhone product record in the catalog (more aspects were returned, but some have been removed for readability):
{
"productSummaries": [
{
"epid": "241976099",
"gtin": [
"0400055810102"
],
"brand": "Apple",
"mpn": [
"MN5W2LL/A"
],
"image": {
"imageUrl": "https://i.ebayimg.com/00/s/ODAwWDQ2MA==/z/ugwAAOSwvD5aTKO3/$_6.JPG?set_id=89040003C1"
},
"aspects": [
{
"localizedName": "Brand",
"localizedValues": [
"Apple"
]
},
{
"localizedName": "MPN",
"localizedValues": [
"MN5W2LLA"
]
},
{
"localizedName": "Processor",
"localizedValues": [
"Quad Core"
]
},
...
{
"localizedName": "Model",
"localizedValues": [
"Apple iPhone 7 Plus"
]
},
{
"localizedName": "Memory Card Type",
"localizedValues": [
"Built-In Memory"
]
},
{
"localizedName": "Model Number",
"localizedValues": [
"A1661 (CDMA + GSM)"
]
}
],
"ean": [
"0400055810102"
],
"upc": [
"0400055810102"
],
"productHref": "https://api.ebay.com/commerce/catalog/v1_beta/product/241976099",
"title": "Apple iPhone 7 Plus - 128GB - Rose Gold (Straight Talk) A1661 (CDMA + GSM)",
"productWebUrl": "https://www.ebay.com/p/Apple-iPhone-7-Plus-128GB-Rose-Gold-Straight-Talk-A1661-CDMA-GSM/241976099"
}
],
"limit": 1
}
Without a limit specified, the call will return up to 200 matching records. You can reduce the number of hits by specifying multiple keywords, such as q=iphone,128GB,GSM. The API searches for keywords in the product's title, description, and brand.
Present the summaries returned by the search call to the seller, who can identify the product that corresponds to the seller's inventory item. If the seller selects a single product, you can then continue to the topic From inventory item to eBay marketplace offer, where you will create an inventory item record and an offer, and publish the offer. If the seller doesn't identify a single matching product, you can refine your search.
Refine the list of candidates
You can request refinement data, which includes histogram information for all aspects of a category that eBay recommends or that you specify. Use the search call with the fieldgroups query parameter set to ASPECT_REFINEMENTS. This example specifies the ID of the category that the iPhone belongs to: 9355.
GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? q=iphone& category_ids=9355& fieldgroups=ASPECT_REFINEMENTS
The response contains a refinement container with all of the aspects that have been previously used in iPhone listings on eBay, with all of the values that were used for each aspect. Each feature value includes matchCount, which indicates how many listings on eBay have previously used this value.
Only the first aspect returned is shown in this example: Features. Many more aspects were returned, but the rest have been removed for readability. Also, some of the values of Features were omitted for readability.
{
"refinement": {
"aspectDistributions": [{
"localizedAspectName": "Features",
"aspectValueDistributions": [{
"localizedAspectValue": "3G Data Capable",
"matchCount": 10355,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7B3G+Data+Capable%7D"
},
{
"localizedAspectValue": "4G Data Capable",
"matchCount": 10176,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7B4G+Data+Capable%7D"
},
{
"localizedAspectValue": "Bluetooth Enabled",
"matchCount": 9954,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7BBluetooth+Enabled%7D"
},
{
"localizedAspectValue": "Fingerprint Sensor",
"matchCount": 6714,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7BFingerprint+Sensor%7D"
},
{
"localizedAspectValue": "GPS",
"matchCount": 6007,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7BGPS%7D"
},
...
{
"localizedAspectValue": "Rugged",
"matchCount": 55,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7BRugged%7D"
},
{
"localizedAspectValue": "TTY Compatible",
"matchCount": 1832,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7BTTY+Compatible%7D"
},
{
"localizedAspectValue": "Voice-Activated Dialing",
"matchCount": 2476,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7BVoice-Activated+Dialing%7D"
},
{
"localizedAspectValue": "Water-Resistant",
"matchCount": 314,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7BWater-Resistant%7D"
},
{
"localizedAspectValue": "Wireless Charging",
"matchCount": 234,
"refinementHref": "https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q=iphone&category_ids=9355&fieldgroups=ASPECT_REFINEMENTS&aspect_filter=categoryId%3A9355%2CFeatures%3A%7BWireless+Charging%7D"
}
]
}],
"dominantCategoryId": "9355"
}
}
Each aspect value is accompanied by matchCount, which indicates how many listings on eBay have previously used the value. Higher numbers indicate aspect values that are more likely to be part of an existing product record. They can also indicate which variation of an aspect value is most likely to be the manufacturer's official terminology (for example, among the colors Red, Scarlet, Crimson, and Ruby). Lower numbers indicate aspect values that might differentiate the inventory item in a listing.
You can present this information to the seller a histogram, from which the seller can select aspect values that match their items, then use those values to filter the results of another search call.
Once you've identified one or a few products as likely matches for a seller's inventory item, you can use the getProduct call with the products' ePIDs to retrieve the complete record for each product, and present the full product details to the seller for final confirmation. When the seller selects a product, use the Inventory API to create an inventory item record based on the product, then offer that item for sale on eBay.