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.

NOTE In August, eBay enabled Phase 2 of the Product-Based Shopping Experience for the US, UK, Australia and Canada (English) marketplaces, and Phase 1 for DE marketplace.

At a glance

  • In PBSE Phase 1, listings within these product lines on the US, UK, AU, CA (English), and DE marketplaces need to be associated with eBay Catalog products as announced in the Spring 2018 Seller Update.
  • In Phase 2 of PBSE, sellers listing within the Phase 2 categories will be expected to associate new and existing listings of any condition and in any format (auction, fixed-price, etc) with products in the eBay Catalog. With Phase 2, the PBSE requirement rolls out to entire leaf categories, and not just certain brands within a category. Sellers will be required to associate all listings with an eBay Catalog product beginning in mid-September 2018.
  • eBay released new APIs, updated existing APIs, and is improving the eBay selling tools to make it easier for developers and sellers to find, edit, and add products in our catalog, and associate them with their listings.
  • Most of the PBSE Phase 2 capabilities of these APIs are ready and can temporarily be tested in the Production environment using predefined test categories. For details, see the PBSE Production Testing Guide.
  • If developers and sellers do not take action to associate their listings with eBay products for Phase 1 and Phase 2 categories, their listings may have minimal or no visibility to buyers, and sellers will no longer be able to successfully revise an existing listing or complete a new listing if you do not use the catalog.

New APIs

The Product-Based Shopping Experience is fully 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 above methods can temporarily be tested in the Production environment using predefined test categories. 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 that are not complying with product-based listing requirements. These product-based listing requirements include the categories/brands that will require association with an eBay catalog product. The operations are summarized below:

  • getListingViolationsSummary - returns the total number of active listings on a given eBay marketplace that are currently not complying with the product adoption compliance type.
  • getListingViolations - retrieves the specific active listings that are not complying with the product adoption compliance type; these listings will need to be revised with catalog product data. The response also includes 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

Trading API

The following update was made to the Trading API for Phase 1 of PBSE:

The following Trading API updates have been made to support Phase 2 of 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