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?categoryId=<category_id> - Use this URL to enter the flow to create a new product in the eBay Catalog. The eBay Category ID of the category you like to place the new catalog product is required as a query paremeter value. Here is an example: https://www.ebay.com/slr/prd?categoryId=9355
  • AppealProductURL: https://www.ebay.com/slr/prd/<ePID_value> - Use this URL to enter the flow to update product information for a specific product in the catalog. Simply append the ePID (unique identifier of the catalog product to revise) to the end of this URL. Here is an example: 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
Note: Unless an id_token parameter is passed in, a seller's eBay credentials will have to be provided in a sign-in page before gaining access to these URLs. If users want to bypass the initial sign-in page, they can pass in an id_token parameter. This id_token can be obtained by using the process 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

Note: If you already have a OAuth user token, proceed to Step 2.

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'

Note: The scope 'SellerBusinessPolicies' may change before we launch this functionality in Production. We will notify all developers if this is the case.

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?categoryId=9355&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.