The Amazon SP-API Sandbox is a testing environment designed for developers to simulate interactions with the SP-API without affecting live seller data. It allows you to build and test your application safely during development.
What is the SP-API Sandbox?#
The Sandbox is a mock environment provided by Amazon
It replicates the behavior of the live SP-API but uses dummy data instead of real seller account data
It helps developers verify their integration and handle edge cases without risking disruptions to live seller accounts
Key Features of the Sandbox#
Simulated Data: The Sandbox provides pre-configured responses to mimic live data (e.g., orders, products, inventory)
API Compatibility: All SP-API endpoints available in production can also be tested in the Sandbox
Error Simulation: You can test error scenarios (e.g., throttling limits, invalid requests) to handle them properly in your app
No Live Impact: Interactions in the Sandbox do not affect live seller accounts or their data
How to Use the Sandbox#
Step 1: Enable Sandbox Mode#
Set the Sandbox parameter to true in your API requests
For example, in the Orders API, use the Sandbox URL: Step 2: Use a Test Seller Account#
Amazon provides mock seller accounts for use in the Sandbox
No real seller authorization is required for Sandbox requests
Endpoints for Sandbox#
The Sandbox environment uses the same endpoint structure as production but with a sandbox subdomain.Example Request in Sandbox#
Here's an example of fetching orders in the Sandbox environment using Python:Expected Output (Simulated Response):{
"payload": {
"orders": [
{
"orderId": "123-1234567-1234567",
"status": "Shipped",
"orderTotal": {
"currencyCode": "USD",
"amount": "100.00"
}
}
]
}
}
Testing Scenarios in the Sandbox#
The Sandbox allows you to simulate the following scenarios:Success Responses#
Test valid API requests to ensure your app works as expected
Error Handling#
Simulate error responses, such as:Throttling (QuotaExceeded)
Unauthorized (AccessDenied)
Invalid parameters (InvalidInput)
Retry Logic#
Validate your retry mechanisms by simulating intermittent failures
Best Practices for Using the Sandbox#
Validate API Workflow#
Use the Sandbox to test the entire OAuth and API interaction workflow
Simulate Edge Cases#
Test unusual scenarios, like missing data or extreme data sizes
Error Simulation#
Use the simulated errors to verify that your app gracefully handles failures
API Transition#
Switch from Sandbox to production only after rigorous testing
Limitations of the Sandbox#
Mock Data: Sandbox data does not reflect live seller accounts or actual orders
No Real Authorization: OAuth flows do not connect to live seller accounts
Feature Differences: Some advanced features available in production might not behave identically in the Sandbox
Switching Between Sandbox and Production#
To switch between Sandbox and Production:
1.
Update the endpoint from sandbox.sellingpartnerapi to sellingpartnerapi
2.
Ensure you use real seller credentials in production
Common Errors#
| Error Code | Description | Solution |
|---|
| Unauthorized | Missing or invalid access token | Verify your token and headers |
| InvalidInput | Incorrect request parameters | Check required parameters and their format |
| QuotaExceeded | Exceeded throttling limits | Implement exponential backoff for retries |
Reference#
