Amazon

Moving from MWS habits to SP-API thinking

Most migration guides map old endpoints to new ones. That part is mechanical. The part that actually causes trouble is that MWS tolerated patterns SP-API does not, and code carried across wholesale tends to work in testing and struggle in production.

Authentication is genuinely different

MWS used long-lived credentials. SP-API uses short-lived access tokens obtained from a refresh token, and the access token expires in an hour.

The failure mode this creates is specific and common: an integration that works perfectly for the first hour after deployment and then starts returning authorisation errors. If your token handling is a one-time fetch at startup, it will pass every test you run and fail overnight.

Refresh on a schedule, not on failure. And store the refresh token somewhere durable, because losing it means going back through authorisation.

Rate limits are per-operation, not global

This is the change that breaks throughput assumptions. Different operations have different limits, and a burst allowance that refills over time rather than a flat cap.

Code that hammered a single endpoint under MWS and got away with it will now exhaust that operation is bucket while the rest of your quota sits unused. The fix is to spread work across operations where you can, and to space calls to the expensive ones.

Reports are asynchronous and that is not a detail

Requesting a report gives you a request id, not a report. You then poll for completion, and when it is ready you get a document reference, which you fetch and decompress separately.

Integrations ported from MWS often keep a synchronous shape around this - request, wait in a loop, read - which ties up a process for minutes at a time. Treat report generation as a job you start and collect later.

Restricted data needs explicit handling

Buyer personal information is gated behind an additional token exchange with its own lifetime. Code that assumes address fields are always present will produce blank shipping labels rather than errors, which is worse, because nothing fails loudly.

Check for presence rather than assuming it. And be deliberate about whether you need the data at all - a lot of workflows want the address once, at purchase, and never again.

What to keep from MWS thinking

Not everything needs rewriting. The discipline of storing what you fetch and not re-fetching it is as valuable as it ever was, and the habit of reconciling settlement against orders rather than trusting order totals is unchanged.

• Change: token handling, rate-limit strategy, report flow, PII assumptions
• Keep: local storage of immutable data, settlement reconciliation, terminal-state marking
• Add: per-operation backoff, a cursor on update time, explicit handling of missing fields

The migration test that matters

Run it for 48 hours before you trust it. Almost every problem in this list - token expiry, rate-limit exhaustion, report timeouts, missing PII - appears after the first hour and before the third day. A ten-minute smoke test will catch none of them.

---