Selling Partner API Sandbox

The Selling Partner API (SP-API) provides two hosted and one local sandbox environment that you can use to test your applications without affecting production data or triggering real-world events. The SP-API static sandbox uses pattern matching to return static, mock responses. The SP-API dynamic sandbox routes requests to a sandbox backend that returns realistic responses based on the request parameters. The Sample AI Sandbox is a locally deployed sandbox that uses AI to generate dynamic responses based on your requests.

🚧

Important

Use the hosted sandbox environments to test functionality, not scalability. Calls to sandbox endpoints are subject to these throttling limits: rate = five requests per second; burst = 15. For more information about throttling, refer to Usage Plans and Rate Limits in the Selling Partner API.

If you use a hosted SP-API sandbox environment to test a call that requires a Restricted Data Token (RDT), you must get the RDT from the production environment and pass it to your sandbox call. For information about RDT, refer to the Tokens API Use Case Guide.

Sandbox support by API

The following table shows which SP-APIs support the static sandbox, dynamic sandbox, sample AI sandbox, or a combination. Use this table to determine the sandbox testing options available for your integration.

SP-API static sandbox

Making static sandbox calls is identical to making production calls, except you direct calls to the Selling Partner API sandbox endpoints. Calling the sandbox endpoints returns static, mock responses for all SP-APIs. You can refer to these mock responses in the Swagger model JSON file for the API that you want to call. For more information, refer to Make a static sandbox call.

The SP-API static sandbox works like many mock-based frameworks. It uses pattern matching to return a specified response when the specified parameters are present. When a developer sends a request that includes the specified parameters, they receive a response defined in one of the following objects:

Static sandbox JSON objects

"x-amzn-api-sandbox":
{
  "static": [
    {
      "request":
      {
        "parameters": 
        {
          …
        }
      },
      "response":
      {
        …
      }
    }
  ]
}

While these objects contain the parameters needed to match a mock response, they don't necessarily contain all parameters required for a successful response. To get a successful response, be sure that your request is valid and includes all required parameters as defined in the corresponding Swagger model.

To make a static sandbox call, use the following procedure:

Step 1. Check the JSON model for request parameters

1. Open the JSON model for your API from the Sandbox support by API table.

2. Search the JSON for an x-amzn-api-sandbox object that contains a "static" array.

The static sandbox JSON objects contain request and response examples for static sandbox calls to the API operation in which they appear. If the request example contains parameters, use them in the following step.

Step 2. Make a static sandbox call to an API

Make a static sandbox call to an API in the same way you would make a production call, with these differences:

1. Include the parameters from Step 1. Check the JSON model for request parameters in your call. If the API requires parameters in addition to those, be sure to also include those required parameters in your call.

2. Direct your call to one of the Selling Partner API sandbox endpoints.

   You should receive a response that matches the payload object contained in the static sandbox JSON object from Step 1.

SP-API dynamic sandbox

Making dynamic sandbox calls is identical to making production calls, except you direct calls to Selling Partner API sandbox endpoints. The dynamic sandbox proxies (forwards) calls to a sandbox backend, which returns an appropriate response given the request parameters. Because you are not limited to exact pattern matching, you can make requests and receive responses that are potentially stateful and react to input. For example, you might want to verify the shipping charges for different ship-to addresses. The sandbox backend capabilities for that API section determine what you can do.

To determine which operations support dynamic sandbox calls, review the Swagger model JSON for your API. An operation supports calls to the dynamic sandbox if the operation includes the following object:

"x-amzn-api-sandbox":
{
  "dynamic": {}
}

The object can be found at either the operation or path level. When at the path level, all operations within the path can make calls to the dynamic sandbox.

To make a dynamic sandbox call, use the following procedure:

Step 1. Check the JSON model for operations that support dynamic sandbox calls

1. Open the JSON model for your API from the Sandbox support by API table. APIs marked "Dynamic" in the table support dynamic sandbox calls.

2. To confirm at the operation level, search the JSON for:

   JSON

   "x-amzn-api-sandbox":
   {
   "dynamic": {}
   }
   

   If the operation contains this object at the path or operation level, the dynamic sandbox is supported for that operation.

Step 2. Make a dynamic sandbox call to an API

Make a dynamic sandbox call to an API in the same way you would make a production call, except direct your call to one of the Selling Partner API sandbox endpoints.

Sample AI sandbox for SP-API

The sample AI sandbox for SP-API is a local development tool for testing SP-API integrations before deploying to production. It validates requests against SP-API OpenAPI schemas, simulates API responses using an AI agent backed by Amazon Bedrock, and allows dynamic test data generation based on your test scenario.

To make an AI sandbox call, use the following procedure:

Step 1. Check prerequisites

• Node.js 22+ (the project extends @tsconfig/node22)
• npm (ships with Node.js)
• AWS credentials configured in your environment with access to Amazon Bedrock (the app uses Claude Haiku via @aws-sdk/client-bedrock-runtime)

Step 2. Download the application

Download the application from GitHub.

Step 3. Install and run

Run the following commands:

npm install
npm run build
npm run start

The server starts on http://localhost:9001 by default.

Report feedback and issues

You can report issues on GitHub.

Sandbox-only operations

The sandbox environments support optional APIs that are sandbox-only and can succeed only when directed to one of the Selling Partner API sandbox endpoints. To determine which operations are sandbox-only, review the Swagger model JSON for the API section. An operation that is sandbox-only contains "x-amzn-api-sandbox-only": true at either the operation or path level. When at the path level, all operations within the path are sandbox-only.

Sandbox-only operations supplement the production API so that you can create test workflows that are not possible using the production API operations. For example, you might have a use case where a data item is instantiated through the user interface, but not through an API. For testing purposes, a sandbox-only API can create the data item, which enables more complete test workflows.

SP-API sandbox endpoints

The SP-API has sandbox endpoints for the North America, Europe, and Far East selling regions. These endpoints apply to the hosted static and dynamic sandboxes only. The sample AI sandbox runs locally on http://localhost:9001.