Matching inventory to catalog products

This is a required part of the listing process for certain eBay categories and brands. It will eventually become required for all eBay listings.

Topics:

Overview

eBay has initiated a system-wide implementation of our Product-Based Shopping Experience (PBSE), in which listings are based on products defined in the eBay catalog. Before sellers can list certain inventory items on eBay, those items must be matched to corresponding catalog products, the details of which eBay uses to generate the listings. The initial set of products that must be matched is small, but will expand steadily. For the current set of affected products, see the Categories/Brands for Phase 1 table in the Product-Based Shopping Experience Playbook.

Each product in the eBay 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 identifiers will be recognized in the future.

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

Attributes and aspects

Each product in the catalog is accompanied by details that include:

  • Title
  • Product identifier(s)
  • Category identifier(s)
  • A description of the product and its features
  • Images of the product

These details are attributes of the product, which are intrinsic to the product on eBay, and are valid for all products.

One additional type of attribute is an aspect. Every product has aspects, but different products have different sets of aspects. This type of attribute differentiates a product from other products in a way that's appropriate to the product's brand and category. Examples of aspects are Color, Size, Storage Capacity, Mud Handling, Maximum Temperature, Artist, Sleeve Length, Compatibility, and so on. As you can see, certain aspects apply only to certain product categories, and some (such as trademarked features) apply only to certain brands. A product's brand and category determine which aspects are used when listing a corresponding item.

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.

You use the Inventory API's createOrReplaceInventoryItem call to include product aspects in a listing. Product aspects are known as item specifics in the Trading, Shopping, and Finding APIs.

Determine the requirement to match a product

There are currently three classes of inventory with respect to product matching (A, B, and C designations are for purposes of this documentation only):

  • A — Inventory that must be listed against a catalog product because of its brand and category
  • B — Inventory for which a matching catalog product exists, but listing against it is currently optional
  • C — Inventory for which a matching catalog product does not yet exist

Note: All inventory listed on eBay will eventually be in class A, and eBay strongly recommends that you anticipate this mandate by attempting to match every inventory item that has a GTIN or a brand + MPN identifier to a catalog product.

If a given inventory item is in class A, you are required to find a matching product on which to base listings of the item. You can determine whether an inventory item is in class A by checking it against the Categories/Brands for Phase 1 table in the Product-Based Shopping Experience Playbook. If you're unsure of your item's category, see Finding categories for a listing or promotion.

If your inventory item is not in class A, you may skip this portion of the inventory-to-offer workflow. However, eBay recommends that you make product matching part of your selling workflow now, as you will need to do so in the future. Additionally, if your inventory item is in class B, the listing process will be much easier and more effective for the seller.

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

Select a matching product

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. For more information, see From inventory item to eBay marketplace offer.

When a matching product is not found

In the event that the seller rejects all of the products you've identified as potential matches, you can request a catalog change from eBay to establish a product that will match. To create or update an eBay catalog product, see Updating the eBay catalog.

For more information about working with the eBay catalog, see the Product-Based Shopping Experience Playbook.