Amazon SP-API Developer Guide
Developer guide to Amazon SP-API covering LWA authentication, IAM roles, per-operation rate limits, Notifications, Restricted Data tokens and production best practices.
Amazon's Selling Partner API is the only supported interface between Seller Central and any third-party system. It replaced MWS in 2022, and the migration forced every integration to re-authenticate, re-scope and re-architect. This guide covers the five areas that trip up first-time SP-API developers: authentication via Login with Amazon and IAM, per-operation rate limits, event-driven Notifications, Restricted Data tokens, and the sandbox versus production gap. If you need a team to build it, start on the Amazon SP-API development page.
TL;DR
- SP-API authentication requires both a Login with Amazon (LWA) app and an AWS IAM role.
- Rate limits are per-operation and per-selling-partner using a token bucket model. Model the budget before you build.
- Notifications via SQS replace polling for most real-time use cases and save significant rate-limit budget.
- Restricted Data tokens are mandatory for any operation returning buyer PII. Enforcement is tightening.
SP-API authentication: LWA plus IAM
SP-API uses a two-layer authentication model. The first layer is Login with Amazon (LWA), which issues an access token scoped to the selling partner who authorised your application. The second layer is an AWS IAM role that you create in your own AWS account and register with Amazon. When you make an API call, you sign the request with your IAM credentials and include the LWA access token. Amazon validates both. This is more complex than MWS but more secure because the IAM role can be scoped to specific actions and resources.
Every SP-API integration needs an AWS account. You do not need to run your application on AWS, but you need an IAM role that Amazon can reference. If your infrastructure is on GCP or Azure, the IAM role still lives in AWS and you call STS AssumeRole from your application. This is a one-time setup cost. The API integration service includes this setup as part of every SP-API build.
Understanding per-operation rate limits
SP-API rate limits use a token bucket model. Each operation has a burst rate (maximum requests in a burst) and a restore rate (tokens added per second). For example, getOrders has a burst of 30 and a restore of 2 per second. That means you can fire 30 requests immediately, then sustain 2 per second indefinitely. Different operations have different limits, and they are independent: calling getOrders does not consume tokens from getInventorySummaries.
The mistake most first-time integrators make is not modelling rate-limit budgets before building. If your integration calls five different operations and your catalogue has 50,000 SKUs, you need to calculate how long a full sync takes at the sustained rate. If the answer is longer than your business can tolerate, move to event-driven Notifications for the operations that support them. This modelling is the first deliverable in every Amazon SP-API development scoping engagement.
Event-driven architecture with SP-API Notifications
Notifications are SP-API's event-driven side. Instead of polling getOrders every 60 seconds, you create a subscription to the ORDER_CHANGE notification type with an SQS queue as the destination. When an order changes, Amazon pushes a message to your queue. The latency is seconds rather than minutes, and the rate-limit budget you save is substantial. The notification types that matter most are ORDER_CHANGE, ANY_OFFER_CHANGED, FEED_PROCESSING_FINISHED, and REPORT_PROCESSING_FINISHED.
Setting up Notifications requires creating an SQS queue, granting Amazon permission to write to it, and calling createSubscription for each notification type. The consumer processes messages, acknowledges them, and handles failures by routing to a dead-letter queue. This is a standard data pipeline engineering pattern. For inventory sync specifically, combining Notifications with the Inventory API means you process changes in near real-time rather than running batch syncs. This architecture pattern powers every inventory and order automation build we ship.
Restricted Data tokens and PII handling
Restricted Data Tokens (RDTs) are short-lived tokens required for any SP-API operation returning buyer PII. The restricted data elements include buyer name, shipping address, and email. You call the Tokens API (createRestrictedDataToken) with the specific operations and data elements you need, and Amazon returns a token scoped to that request. The token has a one-hour lifetime and cannot be broadened. Your application needs a new RDT before each batch of restricted operations.
Any integration handling buyer data, including order fulfilment, customer service and returns, needs RDT support. Amazon is tightening enforcement progressively, so integrations that worked without RDTs in 2024 may start failing in 2026. The custom software development patterns for secure token management apply directly here.
Sandbox versus production: the gap that catches teams
SP-API has a sandbox environment for testing. The sandbox uses the same authentication model but returns canned responses. It does not enforce rate limits, does not return realistic error responses, and does not simulate production latency. An integration that passes all sandbox tests can fail in production due to throttling, timeout handling, or error responses the sandbox never produced. Treat sandbox as a smoke test and production testing against a staging seller account as the actual validation.
MWS to SP-API migration checklist
- Audit every MWS operation your current integration calls and map it to the SP-API equivalent.
- Register a Login with Amazon application and create an IAM role. Test authentication separately.
- Migrate one operation at a time, starting with the one that has the most generous rate limits.
- Implement Notifications for any operation you currently poll.
- Add Restricted Data Token support for any operation that accesses buyer PII.
- Run old and new integrations in parallel for at least two weeks before cutting over.
- Update your marketplace connector documentation to reflect the new model.
Production best practices
- Implement exponential backoff with jitter for throttled requests. SP-API returns HTTP 429 with a Retry-After header.
- Log every API call with the request ID (x-amzn-RequestId header). Amazon support requires this for troubleshooting.
- Store LWA refresh tokens encrypted at rest. They do not expire but can be revoked by the selling partner.
- Monitor rate-limit usage per operation. If you consistently hit the burst limit, your architecture needs to change.
- Keep your SP-API SDK version current. Amazon deprecates SDK versions and new features may require the latest.
Common SP-API errors and what they mean
| Error | HTTP code | What to do |
| QuotaExceeded | 429 | Rate limit hit. Back off with exponential delay plus jitter. |
| InvalidInput | 400 | Request body validation failed. Check Product Type Definitions API for correct schema. |
| Unauthorized | 401 | LWA token expired or IAM credentials invalid. Refresh token and verify IAM trust policy. |
| RestrictedResourceNotFound | 404 | Requesting restricted data without RDT. Call createRestrictedDataToken first. |
| InternalFailure | 500 | Amazon-side error. Retry with backoff. If persistent, open case with x-amzn-RequestId. |
Getting started
Every SP-API integration starts with the same three steps: register as an Amazon developer, set up LWA plus IAM credentials, and map the operations your use case requires. Registration takes 3 to 10 business days. Once registered, the build follows authenticate, call, handle throttling, process, store. If you are evaluating whether to build in-house or engage a team, the Amazon SP-API scoping call gives you a written scope with a fixed price. The Amazon seller tools deep dive covers the full tool landscape if you want context on what the market offers before building custom.
Frequently Asked Questions
What is Amazon SP-API?
SP-API is Amazon's current API for programmatic access to Seller Central. It replaced MWS in 2022 and covers orders, inventory, pricing, reports, feeds, notifications, and restricted data.
How does SP-API authentication work?
Two layers: a Login with Amazon access token scoped to the selling partner, and an AWS IAM role. Both are required on every API call.
What are SP-API rate limits?
Per-operation, per-selling-partner token buckets. Each operation has its own burst and restore rate. Operations do not share budgets.
What are Restricted Data Tokens?
Short-lived tokens required for SP-API operations returning buyer PII. One-hour lifetime, scoped to specific operations and data elements.
How do SP-API Notifications work?
Subscribe to notification types with SQS or EventBridge. Amazon pushes events in real time. Key types: ORDER_CHANGE, ANY_OFFER_CHANGED, FEED_PROCESSING_FINISHED.
Can I still use MWS?
MWS still works but is deprecated and unsupported. All new integrations must use SP-API.
How long does an SP-API integration take?
Single integration: 4 to 6 weeks. Multi-workflow: 8 to 12 weeks. Variable is Amazon developer registration approval time.
What is the SP-API sandbox?
A testing environment returning canned responses. Does not enforce rate limits or return realistic errors. Production testing against a real seller account is essential.