Product-Based Shopping Experience

eBay is moving towards a Product-Based Shopping Experience (PBSE) in 2018. With the new experience, buyers will be able to easily find 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 This experience will roll out to the US, UK, Australia, Canada (English), and Germany sites in 2018, and will roll out to other sites in 2019 and beyond.

At a glance

  • Starting in May 2018, sellers listing within the Phase 1 product lines will be required to associate new and existing listings of any condition and in any format (auction, fixed-price, etc) with products in the eBay Catalog, as announced in the Spring 2018 Seller Update.
  • In mid-August 2018, all Phase 2 functionality is expected to be ready for use by sellers. In addition to the Phase 1 product lines, 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 will roll 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 is releasing new APIs, updating existing APIs, and 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.
  • 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

Two new REST APIs were recently launched to support Product-Based Shopping Experience.

Catalog API (Beta)

For Phase 1, this REST API allows sellers to match their item to a corresponding product in the eBay Catalog. This API does not support parts compatibility. 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
    Status: available in Sandbox and Production environments. See the Testing PBSE APIs in sandbox topic for more information on testing.
  • 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
    Status: available in Sandbox and Production environments. See the Testing PBSE APIs in sandbox topic for more information on testing.

For Phase 2, catalog change request operations will be added to this API. The operations are summarized below:

  • 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
    Status: available for testing in Sandbox environment. See the Testing PBSE APIs in sandbox topic for more information. Becoming available in Production in mid-August 2018 for Phase 1 and Phase 2 PBSE categories.
  • getChangeRequest - this call checks the status of a specific catalog change request
    Status: available for testing in Sandbox environment. See the Testing PBSE APIs in sandbox topic for more information. Becoming available in Production in mid-August 2018 for Phase 1 and Phase 2 PBSE categories.
  • getChangeRequests - catalog change requests can be searched for according to date or status
    Status: available for testing in Sandbox environment. See the Testing PBSE APIs in sandbox topic for more information. Becoming available in Production in mid-August 2018 for Phase 1 and Phase 2 PBSE categories.

Compliance API

This REST 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.
    Status: available in Sandbox and Production environments. In Sandbox, only a canned response is returned. See the Testing PBSE APIs in sandbox topic for more information.
  • 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 include recommended products in the eBay Catalog when available.
    Status: available in Production environment, except for the recommended catalog products feature, which will be delivered in July 2018. Available for testing in Sandbox (including recommended catalog products), but only a canned response is returned. See the Testing PBSE APIs in sandbox topic for more information.

Updated APIs and feeds

Existing REST 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:

  • GetCategorySpecifics - a new ValidationRules.ProductRequired field is returned if a product brand within an eBay category requires association with a catalog product.
    Status: This field is already being returned for PBSE Phase 1 categories/brands in the Sandbox and Production environments.

The following Trading API updates have been made, or are currently in development 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 cannot build their own user flows for these use cases.
    Status: The new URL fields are already being returned for PBSE categories/brands in the Sandbox and Production environments.
  • 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.
    Status: This field will start getting returned in the Sandbox environment for Phase 2 test categories in May 2018, and in the Production environment in mid-August 2018.
  • GetCategorySpecifics: this call will be updated with the following changes:
    • A new flag will be returned to distinguish between product aspects (defined in the catalog product) and item specifics (specific/unique to the actual item/listing).
      Status: This field is already being returned for test PBSE categories in the Sandbox environment. See the Testing PBSE APIs in sandbox topic for more information. It will start getting returned for PBSE categories in the Production environment in mid-August 2018.
    • New item specifics will be added to allow sellers to provide details on bundle listings, modified products, and foreign products.
      Status: These item specific fields will start getting returned in the Sandbox environment in May 2018, and in the Production environment in mid-August 2018.
    • New "maximum length" field will be returned for PBSE categories for some item specifics that require longer descriptions (such as the new details fields that will be introduced.
      Status: This field will start getting returned in the Sandbox environment in May 2018, and in the Production environment in mid-August 2018.
  • (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.
    Status: This field will be available in the Sandbox environment in May 2018, and in the Production environment in mid-August 2018.
  • GetItem/GetSellerEvents/GetSellerList: will be updated to include the ProductReferenceID (ePID) field in the response for each variation in multiple-variation listings.
    Status: This field will start getting returned in the Sandbox environment in May 2018, and in the Production environment in mid-August 2018.

Useful links