Testing in the Sandbox

This section provides information and tips for setting up test users and testing applications on special sites (such as eBay Stores and eBay Motors).


Introduction to Testing

Using the Sandbox

Creating a Sandbox Test User

Generating Auth Tokens for Sandbox Test Users

Testing Your Application's API Access

Creating Stores in the Sandbox

Introduction to Testing

Before you begin running an application in the Production environment, you should fully test the application's features and functionality to make sure it operates in an error-free manner. In addition, you must be certain that it abides by all eBay API usage rules.

To help with your testing, eBay provides the Sandbox environment (called the Sandbox for short). The Sandbox is a special environment designed just for testing, and an application that targets the Sandbox can perform all the operations it can in the Production environment. However, all users, items, and payment funds involved in Sandbox transactions are fictitious. Test users, items, and funds in the Sandbox environment cannot be seen or used in the Production environment and, conversely, real users, items, and money from the Production environment cannot be seen or used in the Sandbox environment.

You can access the Sandbox programmatically, or you can view the Sandbox Web site in a browser. To make use of the Sandbox, create one or more test users and set them up as sellers who list items to the Sandbox. You can list items either programmatically through your application, or you can list items using the interface of the Sandbox Web site. You can also create users to act as buyers to bid on Sandbox items. This gives you the ability to fully test the listing of an item to the completetion of an item purchase.

For specifics and tips on testing individual calls, refer to documentation on those calls in the appropriate API reference. For example, for information on testing the Trading API's GetAccount call in the Sandbox, see the GetAccount call reference.

Using the Sandbox

Operating an application in the Sandbox is essentially the same as operating it in the Production environment. The main difference is that the application needs to address the Sandbox environment instead of the Production environment. For complete information on how to address either the Production environment or the Sandbox environment, see Routing the Request.

The Sandbox duplicates of the functionality that is on the eBay Web site, with a few exceptions. It processes API calls in exactly the same manner as does the Production environment, and it includes a subset of the eBay site's Web pages. The difference is that all the users are test users (created by developers like you) and all the money exchanged is test money.

Use the Sandbox to experiment with function calls, to prototype new routines, and to test your application's business logic. In addition, make sure your application adheres to eBay's Compatible Application Check Requirements before you apply for the Compatible Application Check.

Before you begin working with the eBay API, and before you attempt to connect to the Sandbox, make sure all the tools in your local development environment work properly.

Note: The Sandbox is designed for testing the features and functionality of your applications and, in this sense, you can make up to 5,000 calls per day for function testing. Do not, however, use the Sandbox environment for testing eBay service performance or load handling—high call volumes to the Sandbox may result in an interruption of service for your account.

Generating Sandbox Keys

To use an application in the Sandbox, you must obtain a set of keys for the Sandbox. Follow these steps to generate Sandbox keys.

  1. Register or sign into the eBay Developers Program at https://developer.ebay.com/base/membership/signin/default.aspx.
  2. Go to your My Account page.
  3. In the Sandbox section, click the Create a Keyset link. (You can skip this step if the Sandbox section is already populated with a keyset, as illustrated in Getting Your Keys.)

Creating a Sandbox Test User

Testing an application in the Sandbox requires the use of one or more test users. Test users act as the sellers and buyers of items during the application-testing process in the Sandbox.

Although eBay does provide a few automated Sandbox users (as described above), it is important to create your own test users so you can completely control their Sandbox activities as appropriate for your application's needs.

Registering and Configuring Test Users

The process of registering a test user is different than that for registering a real user in the Production environment. After you register a Sandbox test user, you can use it to buy and sell test items in the eBay Sandbox.

To create a test user in the Sandbox environment, follow these instructions:

  1. Set up an email account for each Sandbox test user. A unique email is required for each test user you create.
  2. On the eBay Developers Program home page, either create a developer's account by clicking the Register link or login by clicking the eBay Developer Login button.
  3. Sign in as a developer, using your eBay Developers Program username and password.
  4. Go to the eBay Sandbox User Registration Tool page.
  5. Create your test user by filling in the Username and Password fields. You can leave the other fields as is.
  6. Click the Create User button.
  7. Save the test user's username and password to a place where you can access them as needed.
  8. Note: eBay automatically adds "TESTUSER_" as a prefix to your test username. So if you used tester1 in the Username field, the name of your user would be TESTUSER_tester1.
  9. If necessary, use the tool to create additional test users.
    • If you are testing only the listing of items, you need only one test user.
    • To test both the buying and selling aspects of an application, you'll need to create at least two test users: One test user to act as the seller and one to act as the buyer. This is because eBay rules forbid a seller from bidding on their own listings, a rule that also applies in the Sandbox.
    • To fully test multi-quantity fixed-price listings, or to test bidding against auction listings, you should create at least three test users: one test seller and two test buyers.
  10. To make API calls in the Sandbox on behalf of test users, you need to create Sandbox authentication tokens (auth tokens) for each test user. See Generating Auth Tokens for Sandbox Test Users. For example:
    • If your application will list items in the Sandbox, then the test user who will be "selling" those items needs a Sandbox auth token.
    • If you will only use the Sandbox UI to test buying your test seller's items, then your test users who are buyers don't necessarily need Sandbox auth tokens.
    • If you are creating a buying application (one that uses PlaceOffer), then the test buyers who use your application need Sandbox auth tokens.
  11. If your test users need to use PayPal in the Sandbox, see Testing Classic API Calls.

Tips on Working with Test Users

For test users to perform actions associated with a test run of an application, eBay allots a pre-determined amount of credit (play money) to each test user's account. The accounts are automatically refreshed to $500,000 each weekend. This means you can safely retry listing items individually and in bulk without having to pay real fees to eBay, and without any obligation to deliver real items to real buyers.

While an application might only supply functionality that serves sellers (listing items only, no bidding or purchasing), you should test the effects of buyer actions to ensure that the application handles all of the interactions the application may encounter when in production.

In general, even if your application just lists items, you should test it for typical scenarios such as users bidding on items, users winning bids, the calculation of shipping costs, and the non-paying bidder.

Likewise, if you are creating an application that caters only to buyers, you should have at least one test user designated as a seller. After all, a buyer cannot bid on an item unless a seller has listed it.

Generating Auth Tokens for Sandbox Test Users

Your application needs authentication tokens to make authenticated and authorized eBay API calls on behalf of your Sandbox test users.

This section describes how to create an auth token for a Sandbox test user.

Note: If you're looking for information about creating and using authentication tokens for real users (in the Production environment), see Getting Tokens.

The following instructions describe how to generate an Auth Token for a registered Sandbox test user. If you want information on how to setup an application to respond to web-based user actions and receive responses to calls it makes to eBay servers, see the Getting Tokens API Flow Tutorial.

  1. Log in to the eBay Developers Program site using your eBay Developers Program username and password.
  2. Click the User Tokens link in the Sandbox keyset.

    User Tokens link

  3. On the Get a User Token page, select Sandbox as the environment, then select the KeySet 1 to use for this user.

    If KeySet 1 isn't available, this means you haven't generated a Sandbox keyset for your Developer account. To generate the key, see Generating Sandbox Keys.

    When you select KeySet 1, the DevID, AppID, and CertID key fields are populated.

    Note that test users do not have their own set of keys. Test user keys are associated with the keyset that belongs to the User ID that created the test user. This is important because some calls (such as ConfirmIdentity) require that you use a keyset in the request.

  4. Click the Continue to generate token button.

    The Sign in to Link Your eBay Account page appears.

  5. Enter the User ID and password for the Sandbox test user for whom you want to generate an Auth Token.

    Remember test user's User ID begins with "TESTUSER_".

  6. Click the Sign in button.

    The Grant application access page appears.

  7. Click the I agree button.
  8. The Token Generation — Final Step page appears, providing the test user's Auth Token and token expiration date.

    Save the Auth Token and expiration date to a place where you can access them whenever you want to make calls on behalf of the respective test user.

  9. Click the Save Token button.

    This allows the test tool to automatically add this token into the call when using the test tool. You are now ready to run calls in the Sandbox environment.

After generating individual authentication tokens for each user, place the respective test user's Auth Token in the eBayAuthToken field of your API request. Make sure to use the proper Sandbox endpoint, depending on the format of your request.

Testing Your Application's API Access

Some API calls have access rules. The rules define how many times an application can use certain API calls each day or hour. Your application also has an aggregate call limit, although not all calls are counted toward the limit.

Your application can detect and report the current API access rules and its current usage with GetApiAccessRules, which shows which API calls have limits, what the limits are, and whether they count toward the aggregate. Each ApiAccessRule defines a rule, and you can parse for various values.

In your application, you can check for the hourly or daily usage of a specific call, say AddItem. Check your application's API access when you test it in the Sandbox, and also while your application runs on the Production server. Call rate limits are set at the sole discretion of eBay. When your application goes through the Compatible Application Check, your application will be rate-limited on an application basis or a per-user basis, depending on your customer base and distribution format. Application-based call limits mean that your application will have a maximum API call cap on a daily and monthly basis. The user-based call limits mean that each user of your application gets their own pool of API calls. One person's usage does not affect another's, so as many people can use your program as you'd like.

To learn more, refer to the Compatible Application Check page on the eBay Developers Program site:


If you decide to go through the Compatible Application Check, ensure that your application complies with eBay policies:


Creating Stores in the Sandbox

If you want to test your application's ability to list items in an eBay Store, you need to set up a storefront in the Sandbox. See Creating a Store.

For conceptual information on eBay Stores, see eBay Stores.

Copyright © 2005–2018 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.