Skip to main content

Topics:

Overview

As part of eBay's Product-Based Shopping Experience (PBSE), every inventory item listed for sale on eBay must eventually be mapped to a product that is defined in the eBay catalog. Listings based on a given product are populated by information that's the same for all listings of that product, and sellers can add their own additional descriptions and images to differentiate their listings. eBay is continually adding more categories and brands to the PBSE mandate, but you can also update the eBay catalog to include the products that your sellers will be able to adopt for their listings without waiting for eBay to add them.

For more information about PBSE, see the Product-Based Shopping Experience Playbook.

After using the Catalog API's search and getProduct calls to find a catalog product that matches a seller's inventory item (see Matching inventory to catalog products), you may encounter one of the following outcomes:

  • Incomplete or inaccurate product record — A product exists in the catalog for which at least one identifier (Brand+MPN or GTIN) matches the seller's inventory item, but one or more of the of the product's attributes or associated aspects is missing a necessary value or has an incorrect value, or an aspect itself is missing. In this case, you can submit a catalog change request to update the product so it can be adopted by the seller.
  • Missing product record — No product exists in the catalog to match the seller's inventory item. The Brand+MPN or GTIN of the seller 's item was not found in the catalog. In this case, you can submit a catalog change request to create a new product so it can be adopted by the seller.

Update an existing product

Product records in the eBay catalog are versioned. When you update an existing catalog product, it will be stored with a new eBay-provided version number. Sellers who are already basing inventory items on the product will be able to continue using the earlier version.

To update an existing product:

  1. (Optional) Use the Taxonomy API's category_tree calls to discover the appropriate category or categories for the seller's inventory item. See Finding categories for a listing or promotion. Even if your seller has already selected a listing category when searching for a matching product, you could discover additional categories with aspects that you want to include in the updated product.
  2. Use the Catalog API's getProductMetadata call to determine the aspects of your selected categories and the values of those aspects that should be added to the aspects and values already associated with the product.
  3. Use the Catalog API's createChangeRequest call to submit a change request to update the product in the eBay catalog for your seller's marketplace. Include the changeRequestType field with a value of PRODUCT_UPDATE, and include the reasonForChangeRequest field with a description of the reason for the request.

The suggestedProduct container of the createChangeRequest call includes the following fields that are required for a product update:

  • The epid field is required to identify the existing product that you want to update.
  • The version field is required to identify the current version of the product record that you're trying to update.
  • The primaryCategoryId and title fields are required, and they can contain either their current values, or new values that you want to provide.
  • If you omit any optional suggestedProduct fields from your request, the existing values in the product record will be retained in the new version. If you include an optional field, the value you provide will replace any existing values in the new version.

Create a new product

To create a new product:

  1. Use the Taxonomy API's category_tree calls to discover the appropriate category or categories for the seller's inventory item. See Finding categories for a listing or promotion. Even if your seller has already selected a listing category when searching for a matching product, you could discover additional categories with aspects that you want to include in the new product.
  2. Use the Catalog API's getProductMetadataForCategories call to determine the aspects of your selected categories and the values of those aspects that should be included in the new product.
  3. Use the Catalog API's createChangeRequest call to submit a change request to create a new product in the eBay catalog for your seller's marketplace. Include the changeRequestType field with a value of PRODUCT_CREATION.

The suggestedProduct container of the createChangeRequest call includes the following fields that are required for a new product:

  • title — This will be displayed at the top of all listings based on the product.

  • description — You should include an informative description of the product, which will be displayed for all listings based on the product.

  • primaryCategoryId — Every inventory item must be part of at least one eBay leaf category. You can also include additional categories to which the new product might belong, using the otherApplicableCategoryIds field.
  • imageUrl — Every inventory item must have at least one image. You're also encouraged to provide as many additional images as possible, using the additionalImageUrls field.

In addition, any recognized product identifiers you have, such as Brand+MPN, EAN, ISBN, or UPC, should also be included in the corresponding fields.

All categories that you specify for the new product have associated aspects and aspect values that will be included in the new product record, but you can also specify additional aspects and their applicable values in the aspects container.

Monitor the change request progress

A successful createChangeRequest call returns the resource URI for the Catalog API's getChangeRequest call, with which you can monitor the progress of your change request. Examine the changeRequestStatus and processStatusMessage fields to determine the status of the request.

A completed request returns one of the following values in changeRequestStatus:

  • APPROVED — The new or updated product is ready to use. The processResolution.epid field contains the product's eBay identifier, with which you can now associate the product with the seller's inventory item.

  • APPROVED_WITH_MODIFICATIONS — Indicates that eBay applied corrections to the suggested product to make it valid. Examine the processResolution.corrections container to view the corrections. If they're acceptable to your seller, you can use the product identifier in the processResolution.epid field to associate the product with the seller's inventory item.

  • REJECTED — Indicates the discovery of conflicting products or violations of eBay standards in the suggested product's attribute or aspect values. Examine the processResolution.conflictingProducts and processResolution.violations containers for details of the issues that you need to resolve before the product can be approved. You can then submit a new createChangeRequest call that's more likely to be approved.

Many requests can be resolved in about one hour, although some issues can delay resolution. If the value of changeRequestStatus is UNDER_EXTENDED_REVIEW, the review has taken more than one hour. Submit the getChangeRequest call periodically and check until the changeRequestStatus field has one of the completed-request values. Depending on the value,

To adopt an approved 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.