Amazon MWS to SP-API Migration: A Practical Guide

Moving an integration from Amazon Marketplace Web Service to the Selling Partner API is not a port. The authentication model, the request lifecycle, the throttling behaviour and the report workflow are all different. Teams that budget for a rename-and-adapt exercise are the ones that overrun. This is what actually changes and where the time goes. ## Authentication is the biggest change MWS used a shared secret and a signature per request. SP-API uses Login with Amazon: your application receives a refresh token per selling partner, exchanges it for a short-lived access token, and sends that as a bearer token. The practical consequences: - You need token storage and refresh logic. Access tokens are short-lived. Every caller needs a shared, thread-safe way to obtain and refresh them, or you will generate a spike of token requests and throttle yourself.

• Refresh tokens are per selling partner. If you serve multiple sellers, you are storing credentials for each, encrypted at rest, with a clear rotation and revocation path.
• Grantless operations exist for a small set of endpoints that are not tied to a specific seller. Know which ones apply to you.
• Registration matters. You register as a developer, create an application, and go through an approval process. If your integration touches Personally Identifiable Information, expect additional scrutiny. Start this early. Approval is a calendar dependency, not an engineering one, and it is the single most common cause of a slipped migration date. > Budget for the approval process before you budget for the code. ## Roles, and why you should ask for fewer SP-API scopes access by role, inventory, pricing, orders, finance, and so on. Requesting roles you do not need makes approval slower and your security review harder. Map each of your existing MWS calls to the minimum role that covers it, and request only those. ## Rate limits behave differently MWS used a quota-and-restore model. SP-API uses per-operation rate and burst limits, returned in response headers, and the values can vary. Design for this explicitly: - Read the rate limit headers and adapt, rather than hardcoding a sleep
• Implement exponential backoff with jitter on 429 responses
• Queue work per operation, not globally, a burst of pricing calls should not starve your order sync
• Treat throttling as a normal operating condition, not an error to alert on A common and expensive mistake is porting a fixed-delay loop from MWS. It will either be far slower than necessary or trip limits under load. ## Reports and feeds are now three-step Under MWS you requested a report and polled for it. Under SP-API the flow is: 1. Create the report or feed document

1. Poll the processing status
2. Download from a pre-signed URL, then decrypt and decompress as specified The document is fetched from storage rather than returned inline. Your error handling needs to cover each stage separately: a report can succeed at creation and fail at processing, and the retry semantics differ. Report types have also been renamed and restructured. Do not assume a one-to-one mapping, check each report you rely on against the current schema, and validate the fields your downstream systems actually consume. ## Regions and marketplaces SP-API endpoints are regional (North America, Europe, Far East) and each covers multiple marketplaces. If you sell across regions you are managing multiple endpoint configurations and, in some cases, separate application registrations. Get this into your configuration model early rather than hardcoding a single base URL. ## A migration sequence that works 1. Inventory your current usage. Every MWS call your systems make, with frequency and business purpose. This is tedious and it is the step most often skipped. You cannot migrate what you have not enumerated. 2. Map to SP-API operations and roles. Identify anything without a direct equivalent, this is where scope surprises live. 3. Build the authentication layer first. Token acquisition, refresh, storage, encryption. Everything else depends on it. 4. Run both in parallel. Where MWS is still available to you, run the new integration alongside and compare outputs on real data. Discrepancies in totals or field semantics are far cheaper to find here than after cutover. 5. Migrate read paths before write paths. Reading wrong data is recoverable. Writing wrong prices or inventory quantities is not. 6. Cut over per marketplace. Not everything at once. ## Where teams lose time - Underestimating approval. Start the developer registration on day one.

• Assuming report schemas match. Validate field by field against what your downstream systems consume.
• Hardcoding rate limits. Read the headers.
• Ignoring the sandbox. It will not catch everything, but it catches structural errors cheaply.
• No reconciliation. Without a comparison against known-good data, you discover problems through customer complaints. ## Worth doing alongside the migration A migration is the one moment when touching this code is already budgeted. It is a reasonable time to: - Introduce proper observability, request rates, error rates, throttling, latency per operation
• Replace polling loops with event-driven notifications where they are available
• Consolidate multiple ad-hoc scripts into one integration service
• Review which per-call costs you are incurring and whether your call patterns can be batched ## Getting help SignX builds and maintains marketplace integrations for sellers and vendors, including SP-API migrations, workflow automation and multi-marketplace reporting. If you are planning a migration or your current integration is throttling under load, tell us what you're running and we will give you an honest assessment of the work involved.