Making a catalog change request using Catalog API

If you discover that your item requires association with a catalog product, but you are either unable to locate your product in the eBay Catalog, or you have located the correct product in the eBay Catalog, but it appears to you that the catalog product has either missing or inaccurate product information, you may have to make a catalog change request to eBay. You can either make a catalog change request using the Catalog API, or you can use stand-alone eBay web flows. The Catalog API process is covered on this page. The stand-alone web flow process is covered in the Making a catalog change request using stand-alone web flows topic.

For best practices on creating eBay Catalog products, see the Catalog best practices guide.

Note: The process described in this section is only applicable to Phase 2. The Catalog API's product metadata and catalog change request operations (for Phase 1 and Phase 2 categories) are currently available for testing in the Sandbox environment. See the Testing Product-Based Shopping Experience APIs in sandbox topic for more information. Additionally, the Catalog API's product metadata and catalog change request operations (for Production test categories) are currently available for testing in the Production environment. For more information on the available test categories, and testing out PBSE functionality with these test categories, see the Testing Product-Based Shopping Experience APIs in production topic. The Catalog API's product metadata and catalog change request operations for actual Phase 1 and Phase 2 categories in Production are expected to become available in mid-August 2018.

Below are two separate processes covering the 'create new catalog product' and 'revise existing catalog product' use cases. Please see the corresponding procedure based on your use case.

After performing one or more search calls with the Catalog API, and you believe that your product is missing from the eBay Catalog, perform the following steps to make a request to eBay to create a new product in the catalog:

  1. Use the getProductMetadataForCategories operation of the Catalog API, or alternatively, use the GetCategorySpecifics call of the Trading API to get product-level aspects for the eBay category ID(s) that are passed in as query parameters. The response payload will include the required and recommended product aspects for the eBay category, and this product aspect data will be needed for Step 2.
  2. Use the createChangeRequest call of the Catalog API to make a request to eBay to create a new product in the catalog. See the createChangeRequest Call Reference documentation for more details on using this call, but please note that the seller will have to pass a value of PRODUCT_CREATION in the changeRequestType field in the request payload to indicate that the request is to create a new product in the eBay Catalog. The seller must provide full details on the product through the request payload, including product title, product description, product identifiers (GTIN(s), Brand/MPN), product aspects, and stock photo(s). For more information on testing the Catalog API catalog change request operations in Sandbox, see the Testing Product-Based Shopping Experience APIs in sandbox topic. For more information on testing the Catalog API catalog change request operations in Production with test categories, see the Testing Product-Based Shopping Experience APIs in production topic.

After performing one or more search calls with the Catalog API, and you believe that you found the right product in the eBay Catalog but that product has one or more product details that are missing or inaccurate, perform the following steps to make a request to eBay to revise an existing product in the catalog:

  1. Use the getProductMetadata operation of the Catalog API to get an array of all supported aspects, aspect constraints, and aspect values for the specified catalog product and its associated or suggested categories, as well as the values currently associated with that product. The array is a union (with duplicates removed) of all returned aspects. The product aspects and details will be needed for Step 2.
  2. Use the createChangeRequest call of the Catalog API to make a request to eBay to revise the existing product in the catalog. See the createChangeRequest Call Reference documentation for more details on using this call, but please note that the seller will have to pass in the catalog product version in the suggestedProduct.version field of the request payload, and a value of PRODUCT_UPDATE in the changeRequestType field in the request payload to indicate that the request is to revise an existing product in the eBay Catalog. The catalog product version is returned in the getProduct operation.

    When requesting to update an existing catalog product, the seller must include all product details (including the details that are remaining the same) of the catalog product. These product details include the epid value for the catalog product for which a revision request is being made, as well as any associated product identifiers (GTIN(s) or brand/MPN), product title, product description, product aspects, and link(s) to product stock photo(s). Besides the epid value, the seller should be passing any one or more product details that either need to be added to the catalog product, or its current value(s) revised. For more information on testing the Catalog API catalog change request operations in Sandbox, see the Testing Product-Based Shopping Experience APIs in sandbox topic. For more information on testing the Catalog API catalog change request operations in Production with test categories, see the Testing Product-Based Shopping Experience APIs in production topic.

All successful createChangeRequest calls will be processed by eBay asynchronously. A successful call is indicated with a HTTP status code of 202 Accepted. An identifier of the catalog change request will be returned through the Location response header. The seller will be able to monitor the status of catalog change request by using the getChangeRequest call of the Catalog API. The seller will just need to pass in the catalog change request identifier at the end of the call URI for the getChangeRequest call.

In the response of the getChangeRequest call, the seller will be particularly interested in the expectedCompletionDate field to get a sense of when eBay will evaluate and make a decision on the catalog change request, as well as the changeRequestStatus field. When a decision is made on the catalog change request, the value of the changeRequestStatus field will change to either APPROVED, APPROVED_WITH_MODIFICATIONS, or REJECTED. For more information on testing the Catalog API catalog change request operations in Sandbox, including testing for different statuses and errors/violations, see the Testing Product-Based Shopping Experience APIs in sandbox topic. For more information on testing the Catalog API catalog change request operations in Production with test categories, including testing for different statuses and errors/violations, see the Testing Product-Based Shopping Experience APIs in production topic.