The Selling Partner API (SP-API) is Amazon’s REST-based API for automating seller and vendor operations, from orders and inventory to reports and pricing. You need a Professional selling account to develop or integrate with it, so if you’re on an Individual plan, upgrade first. Your immediate next step is to create a Solution Provider Portal developer profile and request the roles your use case needs.
TL;DR:
- Most integration failures stem from incorrect role requests, expired tokens, or mismatched headers, not from the API itself.
- Testing in the static and dynamic sandbox environments is essential to prevent live order issues and validate request logic.
- Connecting requires regional endpoints, proper headers, and correctly formatted user-agent strings to avoid silent errors.
- Using official SDKs and sample code significantly accelerates onboarding and reduces setup mistakes.
- Ensuring roles match the intended use case, tokens refresh automatically, and monitoring is active are critical before going live.
Table of Contents
- Quick-start checklist: from zero to your first sandbox call
- How does developer onboarding and registration work?
- Private vs public apps: which authorisation model fits?
- Why sandbox testing matters before you touch production
- Connecting to the SP-API: URIs, headers and signing
- Which SDKs and code samples should you start with?
- What security and compliance checks come before launch?
- Practical troubleshooting notes and where to go deeper
- Author perspective: common traps and how to avoid them
- Authoritative links to official docs, SDKs and samples
- Sources
- FAQ
Quick-start checklist: from zero to your first sandbox call
Everything below assumes you’re starting cold. Follow this order and you’ll avoid the two mistakes that stall most SP-API projects: requesting the wrong roles and skipping the sandbox.
- Confirm you (or your client) hold a Professional selling account. Individual accounts cannot access SP-API.
- Create your Solution Provider Portal account and developer profile.
- Decide whether you’re building a private app (self-authorised, for one seller) or a public app (OAuth, for multiple sellers).
- Request the specific roles you need and complete the security controls, Acceptable Use Policy and Data Protection Policy fields.
- Register your sandbox app and fire a first call through Postman or an official SDK.
- If you’re going public, note the date. Your LWA refresh token needs renewing annually.
How does developer onboarding and registration work?
Onboarding starts with account status. Amazon restricts SP-API to Professional selling accounts, so if a client or your own store is still on Individual, upgrading is the first checkbox to tick before anything else moves forward.
From there, the Solution Provider Portal is where you build your developer profile: business details, application type, and the roles you’re requesting. Amazon reviews this against two documents you’ll need to actually read, not skim: the Acceptable Use Policy and the Data Protection Policy, alongside the Amazon Services API Developer Agreement. These exist because SP-API touches order and customer data, and Amazon wants evidence you’ll handle it properly before granting access.
Role selection is where most first-timers overreach. Amazon grants access by specific role, not blanket API access, so:
- Pick “Orders” if you’re building fulfilment or customer service tooling.
- Pick “Inventory and Order Tracking” for stock-level automation.
- Pick “Pricing” only if you’re actively managing repricing logic.
- Skip roles you don’t need. Unused permissions slow down security review and add audit surface.
Requesting only what you’ll use gets you through review faster.
Private vs public apps: which authorisation model fits?
Your authorisation flow depends entirely on who’s using the app. A private application is self-authorised and built for one seller account, typically your own or a single client’s. A public application uses OAuth 2.0 via Login with Amazon (LWA), designed for software that multiple sellers will connect independently, such as a SaaS platform.
- Private apps: quicker to set up, no OAuth consent screen, but capped at 10 authorisations per application.
- Public apps: built for scale, but require the full LWA OAuth flow and ongoing token maintenance, including token renewal.
- Grantless operations (some notifications and catalogue endpoints) skip the seller-authorisation step entirely and use client credentials instead.
The token lifecycle is where public apps demand discipline. LWA refresh tokens for public applications must be renewed annually, and if you miss that window, your integration silently loses access until the seller re-authorises.
Pro Tip: Build your refresh-token renewal reminder into your deployment calendar the same day you go live, not six months later when you’re chasing a broken integration.
Why sandbox testing matters before you touch production
Amazon gives you static and dynamic sandbox environments, and skipping either one is how sellers end up debugging live orders instead of test data. The static sandbox returns fixed, mocked responses; useful for confirming your request structure works at all. The dynamic sandbox simulates more realistic responses, letting you test edge cases like partial shipments or cancelled orders without touching real fulfilment.
- Start static: verify authentication, headers, and basic response parsing.
- Move to dynamic: test business logic against varied, realistic payloads.
- Run both through Postman first, then replicate the working calls in your SDK test scripts.
Sandbox calls make no impact on production data, which is exactly why they’re non-negotiable before you flip any switch live.
Connecting to the SP-API: URIs, headers and signing
Every SP-API call starts with the right regional endpoint, since Amazon runs separate URIs for North America, Europe, and Far East marketplaces. Get the region wrong and you’ll get authentication errors that look like a credentials problem but aren’t.
Your request needs four headers to succeed: host, x-amz-access-token, x-amz-date, and user-agent. Connecting to the SP-API requires a Login with Amazon access token alongside these headers, and the user-agent format is stricter than most developers expect.
- Format:
ApplicationName/Version (Language=LanguageVersion; Platform=PlatformVersion). - Escape reserved characters properly, or Amazon rejects the request without a clear error message.
- Restricted operations (buyer PII, for instance) also need a Restricted Data Token (RDT), fetched separately before the actual call.
Incorrectly formatted user-agent headers are one of the most common “silent” failure points developers report: the call fails with no obvious clue that formatting, not authentication, is the culprit. If a request fails without a clear error, check the header format before you assume your token is bad.
Which SDKs and code samples should you start with?
Skip writing raw REST calls from scratch. Amazon’s official SDKs handle most of the authorisation and request-signing overhead for you, which is exactly the boilerplate that trips up new integrations.
- Start with the SDK matching your existing stack: Java, Python, or Node all have official support.
- Pull working examples directly from the amzn/selling-partner-api-samples GitHub repository, which includes multi-language code recipes.
- Use Postman collections from the same repo to validate calls before wiring them into your codebase.
Starting from SDK examples rather than blank REST calls typically shaves days off your first working integration.
What security and compliance checks come before launch?
Amazon treats security as a prerequisite, not an afterthought, and expects developers to work through its Guard Implementation Guide from the start of the project rather than retrofitting compliance later.
- Review the Acceptable Use Policy and Data Protection Policy before requesting roles, not after.
- Build rate-limit handling into your integration from day one. Throttled requests need backoff logic, not retries on a loop.
- Log every API call and response code so failures are traceable, not guesswork.
- Set up monitoring and alerting for token expiry and error-rate spikes before production traffic starts.
Pro Tip: Treat your pre-production checklist as a gate, not a suggestion: confirm roles match usage, tokens rotate automatically, and logging is live before the first real order flows through.
Practical troubleshooting notes and where to go deeper
Most auth failures trace back to three things, in this order: an expired or wrong-scope token, a malformed user-agent header, or a role that was never actually granted. Check those before assuming the API itself is broken.
- Rotate tokens automatically rather than manually. Treat refresh-token renewal as part of your rolling-deployment checklist, with alerts before expiry, not after.
- For complex auth flows, the GitHub samples repo’s runnable labs often surface fixes faster than static documentation.
- For catalogue-heavy integrations, pairing SP-API data with AI-driven product copy tools can shorten the path from raw listing data to updated content at scale.
Once your API connection is live and reliable, the real value shows up in what you build on top of it: automated profit tracking, PPC insights, and inventory alerts that simplify daily operations.
Osellpa’s own integration work with Amazon’s seller dashboard and analytics tools follows this exact sequence, which is why teams tend to reach reliable automation faster once the sandbox groundwork is solid.
Author perspective: common traps and how to avoid them
Header formatting and token lifecycle cause more early failures than anything else in SP-API integrations, not complex business logic. A sandbox-first approach consistently shortens the path to production, because it surfaces auth mistakes before they touch real orders. Before go-live, check three things: roles actually match your use case, refresh tokens rotate automatically, and monitoring catches expiry before customers do.
— Harry
Authoritative links to official docs, SDKs and samples
- Private developer onboarding: account eligibility and setup.
- Public app authorisation: OAuth and token renewal rules.
- Sandbox documentation: static vs dynamic testing.
- Connecting to the SP-API: headers and signing.
- GitHub samples repo: code recipes by language.
Once your integration is stable, tools like Osellpa’s profit and loss software and PPC optimisation reports turn that raw SP-API data into decisions you can act on without building your own dashboard from scratch.
Sources
FAQ
What Is the Amazon SP-API?
The Selling Partner API is Amazon’s REST API for automating seller and vendor operations, covering orders, inventory, pricing, reports, and more, in place of manual Seller Central work.
How Do I Access the Amazon SP-API?
Upgrade to a Professional selling account if you haven’t already, then register a developer profile through the Solution Provider Portal and request the specific roles your integration needs.
Is Amazon’s SP-API Free to Use?
Amazon doesn’t charge a separate fee to access the SP-API itself, though your seller account must be on a Professional plan, which carries its own monthly subscription cost.
How Do I Use the SP-API Step by Step?
Register your Professional account and developer profile, choose private or public app authorisation, request roles and complete security checks, test thoroughly in the sandbox, then move to production using an official SDK.
What’s the Difference Between Private and Public Applications?
Private apps self-authorise for a single seller and cap at 10 authorisations; public apps use OAuth 2.0 via Login with Amazon and require annual refresh-token renewal for use across multiple seller accounts.
