Selling Partner API Sandbox

The Selling Partner API (SP-API) provides two sandbox environments 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.

🚧

Important

Use the 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 an 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 restricted operations for which you need an RDT, refer to the Tokens API Use Case Guide.

SP-API static sandbox

Making sandbox calls to the SP-API static sandbox (static sandbox) is identical to making production calls except you direct the 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, in that it uses pattern matching to return a specified response when the specified parameters are present. A developer receives a response defined in either of the following objects when they send a request that includes the specified parameters:

Static sandbox JSON objects:

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

Note that while these objects will contain the parameters that are needed to match a mock response, they do not necessarily contain all of the parameters that are 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 file for request parameters

1. Go to the welcome page.

2. In the left navigation pane locate the folder for the API for which you want to make a sandbox call.

3. Choose the Swagger model JSON file for the API that you want.

   The JSON code displays.

4. Search the code for a x-amzn-api-sandbox object that contains a "static" array.

The static sandbox JSON objects will 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 file 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 calls to the SP-API dynamic sandbox (dynamic sandbox) is identical to making production calls except you direct the calls to the Selling Partner API sandbox endpoints. Dynamic sandbox calls are proxied (that is, forwarded) 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. What you can do is limited only by the capabilities supported by the sandbox backend provided for that API section.

You can determine which operations support dynamic sandbox calls by reviewing the Swagger model JSON for the API that you want to call. 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 file for operations that support dynamic sandbox calls

1. Go to the welcome page.

2. In the left navigation pane locate the folder for the API for which you want to make a sandbox call.

3. Choose the Swagger model JSON file for the API that you want.

   The JSON code displays.

4. Search the code for:

   JSON

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

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

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.

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. You can determine which operations are sandbox-only by reviewing 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 only, a sandbox-only API could be provided that creates the data item to allow for more complete test workflows.

SP-API sandbox endpoints

The SP-API has sandbox endpoints for the North America, Europe, and Far East selling regions.