Product-Based Shopping Experience

eBay is transforming the shopping experience to be product-based. A Product-Based Shopping Experience (PBSE) will make it easier for buyers to find the merchandise that meets their search criteria, and quickly decide which products they want to purchase. Please visit our Seller Center for more information on why eBay is moving to the new experience.

Sellers and developers looking for complete integration details can skip directly to the Product-Based Shopping Experience Playbook. Note that sellers and developers have the option of integrating with PBSE using the traditional Trading API or the new REST-based Inventory API.

New APIs

The Product-Based Shopping Experience is supported by new public APIs - Compliance API and Catalog API. Both APIs are summarized below.

Catalog API (Beta)

This RESTful API allows sellers to match their item to a corresponding product in the eBay Catalog. The operations are summarized below:

• search - search for a matching catalog product using a GTIN value, an MPN value, a keyword, or one or more product aspects.
• getProduct - returns detailed information on a specified catalog product, including product title, product description, product identifiers, stock photo(s), product aspects, primary category, and a link to the associated eBay product page.
• getProductMetadataForCategories - this call allows a seller to retrieve an array of all supported aspects, aspect constraints, and aspect values for specified eBay categories. This metadata will assist sellers when they make a catalog change request.
• getProductMetadata - this call allows a seller to retrieve an array of all supported aspects, aspect constraints, and aspect values for the specified catalog product and its associated or suggested categories. This metadata will assist sellers when they make a catalog change request.
• createChangeRequest - this call allows a seller to make a request to eBay to add a new product to the catalog, or to request a change to an existing catalog product that has missing or inaccurate information.
• getChangeRequest - this call checks the status of a specific catalog change request.
• getChangeRequests - catalog change requests can be searched for according to date or status.

Note: The catalog change request methods can only be tested in test categories in the Production or Sandbox environments. For details, see the PBSE Production Testing Guide.

Compliance API

This RESTful API allows sellers to retrieve detailed information on listing violations for active listings. The operations are summarized below:

• getListingViolationsSummary - returns the total number of active listings on a given eBay marketplace that are currently considered non-compliant.
• getListingViolations - retrieves the specific active listings that are currently considered non-compliant. The response may also include recommended products in the eBay Catalog when available.

Updated APIs and feeds

Existing RESTful API and Trading API calls were updated to support Product-Based Shopping Experience.

Inventory API

• The product.epid field of createOrReplaceInventoryItem was added to enable the ability to directly associate an inventory item with a catalog product using an ePID value (instead of a GTIN value).

Trading API

The following Trading API updates have been made to support PBSE:

• GeteBayDetails: new URLs returned in the URLDetails container of the response that take seller to eBay pages where they can make requests to add products to the eBay Catalog, make requests to revise existing catalog products, and to get statuses of all catalog change requests. Partners can use these URLs if they prefer not to build their own user flows for these use cases. See the Making a catalog change request using stand-alone web flows topic for more information on how to make a catalog change request using the stand-alone web flows.
• GetCategoryFeatures: new ProductRequiredEnabled field returned in the Category container of the response if all products within an eBay category require association with a catalog product.
• GetCategorySpecifics: this call was updated with the following changes:
  • A new flag is returned to distinguish between product aspects (defined in the catalog product) and item specifics (specific/unique to the actual item/listing).
  • New item specifics added to allow sellers to provide details on bundle listings, modified products, and foreign products.
  • New "maximum length" field is returned for PBSE categories for some item specifics that require longer descriptions (such as the new details fields).
• (Add/Revise/Relist)FixedPriceItem: new ProductReferenceID field added to VariationProductListingDetails container to allow sellers to associate a variation (within a multiple-variation listing) with a catalog product.
• GetItem/GetSellerEvents/GetSellerList: updated to include the ProductReferenceID (ePID) field in the response for each variation in multiple-variation listings in PBSE categories.

Taxonomy API

The following Taxonomy API update has been made to support PBSE:

• getItemAspectsForCategory: this new method returns a list of aspects that are appropriate or necessary for accurately describing products in the specified leaf category. This call is very similar to the GetCategorySpecifics call of the Trading API.

Metadata API

The following Metadata API update has been made to support PBSE:

• getProductAdoptionPolicies: this new method is used to view the eBay leaf categories that require that listings within the category be associated with an eBay Catalog product. A productRequired boolean field is returned for each category that requires an eBay Catalog product. This call can be used instead of the GetCategorySpecifics call (using ProductRequiredEnabled as a FeatureID value) of the Trading API.

Useful links

• Product-based Shopping Experience Playbook
• Fall 2018 Seller Update - Inventory Optimization
• Summer 2018 Seller Update - Inventory Optimization
• Spring 2018 Seller Update - Inventory Optimization
• Tech Blog: A Reimagined Shopping Experience
• Tech Blog: How Developers Power eBay's Product-Based Shopping Experiences
• German Translation of PBSE Landing Page (Phase 1)
• Chinese Translation of PBSE Landing Page (Phase 1)
• German Translation of PBSE Playbook (Phase 1)
• Chinese Translation of PBSE Playbook (Phase 1)

Other helpful Catalog API links:

• Catalog API Overview
• Catalog API Release Notes
• Matching inventory to catalog products

Other helpful Compliance API links:

• Compliance API Overview
• Compliance API Release Notes
• Using Compliance API reason codes to revise listings

Why is eBay making this change?

As we move toward a Product-Based Shopping Experience, it has become necessary for sellers to tell us exactly what items they are offering because buyers expect a more streamlined online shopping experience. The best way to achieve this is to select the appropriate product in the eBay Catalog during the listing process.

What is the eBay Catalog?

The eBay Catalog is a centralized repository of product information that allows buyers and sellers to achieve a common understanding of what is for sale.

How can I associate my listing with a product that's in the eBay Catalog?

When you start a listing, you will be able to search for a product in the eBay Catalog by using an identifier like UPC, EAN, or ISBN, or keywords. Once you have selected the product from the catalog, you will continue with the rest of the listing experience. Starting in May 2018, if we determine that you are selling an item in the select product lines, but you did not associate it to a product from the eBay Catalog, you will be unable to complete the listing.

What are product identifiers?

Product identifiers are unique numbers or codes for products that help buyers recognize and find them. Most new, branded products have unique product identifiers. These can include an item's Global Trade Item Number (GTIN), such as UPC, EAN, or ISBN, as well as the combination of brand and manufacturer part number (MPN).

What is a GTIN?

A GTIN (Global Trade Item Number) is a unique number that identifies products and services. GTINs can include an item's Universal Product Code (UPC), European Article Number (EAN), or International Standard Book Number (ISBN).

When will I need to use the eBay Catalog?

We strongly encourage you to begin adopting the eBay Catalog now for the required product lines. Adopting means that in the listing process, you select a product from the catalog (by searching by identifier like UPC, EAN, ISBN or keyword) that corresponds to the item you are listing, and you associate that product in the catalog to your listing. Starting in May 2018, in order to complete your listing for an item that is within the select product lines, you will be required to match your item to that product in the catalog. Later this year, we will expand this requirement to more categories and product lines.

If I use an eBay Catalog product, will I be able to customize my listing?

Customizing your listing will depend on the item condition. For new products, additional pictures are optional. For other conditions (e.g., used, refurbished), you will continue to be required to include additional pictures and item information to help buyers with their purchasing decisions.

What if I discover inconsistent information in a product entry?

Seller Hub users can suggest changes to the catalog information for a product while they are listing by clicking a flag icon next to the product in question. In addition, if you spot inaccurate information in the eBay Catalog you can email us at sdsupport@ebay.com. In Phase 2, API users can submit catalog change requests via the Catalog API. See the Making catalog change requests topic.

Will I need to use the eBay Catalog for multiple variations (multi-SKU) listings?

Yes. In order to comply with the new catalog requirements, you are required to provide a valid GTIN (UPC, EAN or ISBN) for each variation in multi-SKU listings within the initial product lines. In Phase 2, each variation will require a valid eBay Product ID [ePID] in PBSE categories.

If I'm selling my items in bundles, will I need to use the eBay Catalog in the select categories?

Yes. The way you should select a product in the eBay Catalog will vary depending on what type of bundles you offer:

• Manufacturer bundles that are sold in a single package usually have a dedicated GTIN (UPC, EAN or ISBN) associated with them and should be found in the eBay Catalog.
• For seller-created bundles with a clear primary product (e.g., iPhone + accessories such as a case, selfie stick, etc.), select the primary product from the eBay Catalog as the product for your listing (in the example, select the corresponding iPhone from the eBay Catalog) and select the bundle check box (or Bundle Listing item specific if using API).
• For seller-created bundles with no clear primary product where all included items are related, choose what you believe to be the most popular product in the bundle and select it from the eBay Catalog as the main product for the listing and check the bundle check box (or Bundle Listing item specific if using API).
• For seller-created bundles that do not have a clear primary product and there is no clear relationship between products in the bundle, don't list the items as a bundle, but create separate listings for each item instead.

In all of these cases, apart from selecting the right product from the catalog, you must also set the "Bundle Listing" item specific to "Yes" and clearly itemize what's included in the bundle in the item description field. In Phase 2, eBay will be introducing a 'Bundle Details' item specific, and then the seller should use this item specific instead of the item description field to describe the bundle.

Will I need to use the eBay Catalog if I am selling my items in lots?

Yes. The way you should select a product in the eBay Catalog will vary depending on what type of lots you offer:

• When listing a lot of a single-pack product (e.g. a set of 4 Nests):
• Pick the product.
• Fill out the "Lot Size" field with the right value.
• In the above example, choose the appropriate Nest product and set Lot Size to 4.
• When listing a lot of a multi-pack product (e.g. a lot of 75 12-pack AA batteries):
• Pick the appropriate product for the multi-pack
• Fill out the "Lot Size" field with the right value
• In the above example, choose the appropriate product AND set Lot Size = 75.

How do I list a foreign product for initial product lines?

You can select a "proxy" product for international versions available for every iPhone and iPad product and specify the exact carrier/network in the listing flow. For example, if you want to list a UK version of an “Apple iPhone 6s 128GB Vodafone” on the US site with an EAN=888462563048 on the box, search for iPhone 6s 128GB Black during the US selling flow. You will see the following results. Select product e4:

ePID	Product Name	Brand	Carrier
e1	Apple iPhone 6s 128GB Black US Version AT&T	Apple	AT&T
e2	Apple iPhone 6s 128GB Black US Version Verizon	Apple	Verizon
e3	Apple iPhone 6s 128GB Black US Version T-Mobile	Apple	T-Mobile
e4	Apple iPhone 6s 128GB Black INTERNATIONAL Versions	Apple	Not Specified

If you search by GTIN (i.e. EAN=888462563048) instead, product e4 will display as the only result, which should then be selected. If your item is locked to a specific network, or is unlocked, be sure to include this information in the title of your listing.

What do you mean when you say my listings won't show up in search?

Under the new Product-Based Shopping Experience, listings that have not adopted a product in the eBay Catalog for the Phase 1 product lines above or Phase 2 categories will not display in the search results page.

Will catalog information be accessible through all eBay listing tools, third-party tools, and APIs?

All eBay listing tools and APIs will allow eBay Catalog products to be associated with your listings. Third-party tools will have access to this information via API. eBay is engaging directly with third-party developers about this as well. However, we encourage you to check with your third-party tools provider in preparation for the change.

Will this requirement apply for listings with all item conditions, aftermarket customization, bundles, and lots?

Yes, this requirement applies to all item conditions (i.e. new, used, refurbished), as well as customized items, bundles, and lots.

How do I get the top product slot on the new product page?

On a product page, when multiple listings of the same item have been associated with products from product lines in the eBay Catalog, your items will compete with other sellers' listings for the chance to be featured in the top pick or the primary position on the product page. You must be at above standard, ensure your items remain in stock, and offer competitive shipping and pricing to improve your chances of winning the top pick.

How will the Product-Based Shopping Experience impact my promoted listings?

Promoted listings will continue to be featured in search results as well as within seller offers on our product pages. As the buyer experience evolves, we will continue to enhance these placements to more intelligently drive traffic to your listings.

When will product-based search apply?

The buyer experience will only be defaulted to product based for very specific buyer queries, directly matching the products and categories identified, and always more than a month after the beginning of the selling enforcement. Sellers will be given multiple months of advance notice before any expansion of the product based experience.