Product-Based Shopping Experience

NOTE Due to the rollback of the Product-Based Shopping Experience mandate for all eBay categories (and brands within those categories), sellers will no longer be required to associate an eBay catalog product to the listing in any categories. Although the mandate has been rolled back, it can still be very useful to sellers (and buyers searching for their items) if a listing is associated with an eBay catalog product, if one is available for their product. Sellers can use the search operation in the Catalog API or the FindProducts call in the Shopping API to search for matching eBay catalog products.

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

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