Making a catalog change request

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. Each of these options are explained in detail in the following two sections.

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

Making a catalog change request using Catalog API

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.

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.

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.

Making a catalog change request using stand-alone web flows

Third-party developers can use eBay's stand-alone web pages to enable sellers to file requests to add or update products in the eBay catalog and view the status of these requests, without building their own user interface on top of the Catalog API.

All of these pages are embeddable and you can use OAuth tokens to pull session tokens which will allow your users to access these pages without signing in to eBay. The process to use these pages and pull the session tokens is outlined below.

All of the functionality below is available in our Sandbox environment for testing. Just simply use the sandbox subdomain ('sandbox.ebay.com') instead of the eBay domain ('ebay.com').

Stand-Alone URLs

You can use the Trading API's GeteBayDetails call to get the specific URLs for the site on which you are listing. When you run this call, include the DetailName field and set its value to URLDetails. The GeteBayDetails call will return the following URLs in the URLDetails container for the US site:

• CreateProductURL: https://www.ebay.com/slr/prd - Use this URL to create a new product in the eBay Catalog
• AppealProductURL: https://www.ebay.com/slr/prd/ - Use this URL to update product information for a specific ePID in the catalog. Simply append the ePID to the end of this URL. (e.g. https://www.ebay.com/slr/prd/149167716)
• ManageProductURL: https://www.ebay.com/slr/prd/status - Use this URL to view the status of any create or revise product requests

These URLs will require an id_token parameter which can be pulled using an OAuth user token as outlined below.

Authentication and Launching the URLs

The steps below describe how to get an OAuth token, pull a session token, then launch the stand-alone web URLs.

Step 1: Authenticate Seller and Fetch OAuth token

An OAuth user token is required before pulling a session token. This step will need to be repeated for each seller, but need not be repeated for each session. See a more detailed description of how to use OAuth on eBay.

1. Authentication
   1. Send the user to the eBay authentication flow to grant your application access to their account using the following URL: https://auth.ebay.com/oauth2/authorize?client_id=<application name>&response_type=code&redirect_uri=<application's RUname>&scope=<include relevant scopes>
   2. The values required for this URL can be obtained from the eBay developer portal's Application Keys page (sign-in required).
2. Fetching an OAuth or Access token

   After successful authentication (from the previous step), eBay forwards the request to a page where the seller grants the application access. Here is the URL: http://www.ebay.com/api/auth/accept.html?access_token=<access token>. Below summarizes how to do this from a Web tool and from a desktop tool:

   • Web tool

     The application that receives the forwarded request should parse the URL to fetch the value of the 'access token' parameter from it. Store this token in the application for use in Step 2.

   • Desktop tool

     Intercept the URL and extract the value of the 'access_token' parameter from it. Store this token in the application for use in Step 2.

Step 2: Fetch Session Token

A session has a shorter life than an access token. It is intended for specific user sessions. This step will be required for each user session. To fetch a sesssion token, invoke the following URL, and insert the appropriate values for client_id, redirect_URL, client_secret, scope_value, and client_credentials:

https://auth.ebay.com/ws/eBayISAPI.dll?OAuthAuthorize2&client_id=<client_id>&redirect_uri=<redirect_URL
>&client_secret=<client_secret>&scope=<scope_value>&grant_type=client_credentials

All of these values are obtained from the Developer Portal (sign-in required). The context of these values are summarized below:

• client_id: application name
• redirect_uri: RU name for the application
• client_secret: this is the access token obtained in the previous step. Please make sure that the value is URL encoded.
• scope: set this to a URL-encoded value of the following string. "scope://EBAYSSO/SCOPEDTOKEN:SellerBusinessPolicies"
• grant_type: set this to 'client_credentials'

The response to this GET call is a JSON object that holds the session token. The field "id_token" in the response contains the session token. An example is shown below:

{"id_token":"v^1.1#i^1#r^1#I^3#f^0#p^3#t^Ul4yX0JCMUNFQzg5NzQ4RUU5QzU0N0Q4MDM1RDc0Q0VFNTg1I0VeNTE2"}

Be sure to URL encode this id_token before launching the stand-alone pages.

Step 3: Launch stand-alone web URLs

1. Call GeteBayDetails in the Trading API with the appropriate listing Site ID header, and include the DetailName field and set its value to URLDetails, and look for the CreateProductUrl, AppealProductUrl, and ManageProductUrl in the URLDetails container in the response.
2. Invoke the appropriate URL for the user with the id_token captured in the previous step. Make sure to encode the id_token when passed as a parameter. Examples are shown below:
   • CreateProductUrl

     https://www.ebay.com/slr/prd/?id_token=<session_token>

   • AppealProductUrl for the ePID, 123

     https://www.ebay.com/slr/prd/123?id_token=<session_token>

   • ManageProductUrl

     https://www.ebay.com/slr/prd/status?id_token=<session_token>

If you have difficulty with any of these steps, please review the detailed documentation links above or contact Developer Technical Support if you still need assistance.