Amazon Selling Partner API (SP-API): definition, limits and mistakes
Updated · By Ecomsellertool editorial team
SP-API, the Amazon Selling Partner API, is the REST-based API that sellers, vendors and their authorized apps use to read orders, inventory, finances and reports, and to update listings, prices and shipments. An app exchanges a stored refresh token through Login with Amazon for an access token that lasts one hour. Most operations have their own rate and burst limit for each seller-and-app pair, so reliable integrations lean on notifications instead of constant polling.
- Amazon's developer docs define SP-API as a REST API for sellers' and vendors' own order, shipment, payment and inventory data.
- Calls are authorized through Login with Amazon: a stored refresh token is exchanged for an access token valid for 3,600 seconds.
- Rate limits use a token bucket, and most apply per selling partner and application pair; searchOrders defaults to 0.0056 requests per second with a burst of 20.
- App client secrets must be rotated every 180 days, and sellers must reauthorize a public app every 365 days or whenever it adds a role.
- Buyer PII such as names and addresses needs a restricted role like Direct-to-Consumer Shipping or Tax Invoicing; Orders API v0 and some other operations also need a Restricted Data Token, but v2026-01-01 does not.
- Orders API v0 operations such as getOrders were deprecated on January 28, 2026 and are removed on March 27, 2027, in favor of Orders API v2026-01-01.
Definition: Amazon Selling Partner API (SP-API)
The Amazon Selling Partner API (SP-API) is Amazon's REST-based API that lets sellers, vendors and the applications they authorize read and update their business data, including orders, shipments, payments, inventory, listings and reports, so Amazon operations can be automated instead of run through Seller Central screens.
SP-API is the main pipe between an Amazon selling account and the software that runs it; repricers, replenishment planners, reimbursement tools and profit dashboards typically read and write through it.
What does SP-API cover?
It is a family of APIs, each with its own versions and limits. The ones an operations team touches most:
| Job | SP-API area | Detail worth knowing |
|---|---|---|
| Pull orders | Orders API | v2026-01-01 replaces v0, whose getOrders calls are removed March 27, 2027 |
| Publish listings and prices | Listings Items API, JSON_LISTINGS_FEED | The XML and flat-file listing feeds were removed December 3, 2025 |
| Track FBA stock | FBA Inventory API | The FBA_INVENTORY_AVAILABILITY_CHANGES notification carries a snapshot for every eligible store in the region |
| Reconcile money | Finances API | Recent orders (roughly the last two days) can be missing from transaction results |
| Pull bulk data | Reports API, Data Kiosk | Reports are asynchronous: request, wait, download |
| React to events | Notifications API | Delivered to Amazon SQS or Amazon EventBridge |
Calls go to one of three regional endpoints: North America, Europe (which also serves India, the UAE and Saudi Arabia) and Far East (Japan, Australia and Singapore).
How do SP-API rate limits work?
Throughput follows a simple formula. Each operation has a usage plan: a rate, the tokens added to your bucket per second, and a burst, the bucket's size. Every call spends a token, and an empty bucket returns HTTP 429. Most limits apply per selling partner and application pair.
Sustained calls per hour = rate × 3,600 (once the burst is spent)
searchOrders defaults to 0.0056 per second with a burst of 20: twenty calls at once, then about 20 an hour. createReport allows 0.0167 per second, about 60 an hour. getListingsItem allows 5 per second, or 18,000 an hour. Some operations use dynamic usage plans that Amazon adjusts per seller, and the x-amzn-RateLimit-Limit header that reports your plan is not always returned.
Why does it matter for operations and growth?
Many revenue-leaking operations gaps are data-timing problems underneath. Replenishment needs sales velocity and FBA stock within hours, not from last week's export: that is the replenishment gap. Reimbursement work needs inventory events matched to finance transactions: that is the FBA reimbursements gap. An event-driven connection that respects limits and current versions lets those workflows run without anyone downloading CSVs.
What mistakes break SP-API integrations?
- Polling for everything. Subscribing to ORDER_CHANGE, REPORT_PROCESSING_FINISHED or LISTINGS_ITEM_ISSUES_CHANGE saves calls. Amazon still recommends a backup pull in case delivery is delayed.
- Retrying 429s immediately. A 429 is retryable, but only with back-off.
- Letting credentials lapse. Client secrets must be rotated every 180 days, with a warning 90 days out; after the deadline, calls fail. Sellers also reauthorize a public app every 365 days.
- Handling buyer data loosely. Names and addresses are PII and need an approved restricted role; older operations such as Orders v0 also need a Restricted Data Token.
- Building on retiring versions. Read the deprecation schedule before you build, and plan migrations as releases.
- Expecting ad data. Campaigns run through the separate Amazon Ads API.
- Outgrowing a private app. It allows 10 self-authorizations, which a multi-brand group can reach.
How does Growth OS use SP-API?
Ecomsellertool has built on Amazon's seller APIs since 2017. Growth OS connects through SP-API on your own accounts and treats the connection as infrastructure:
- Events first, pulls as backup. It is built to start work from order, inventory, listing-issue and report notifications, with scheduled pulls to catch anything missed.
- Per-operation pacing. It is built to pace each account's calls against each operation's rate and burst, with order sync prioritized over bulk report pulls.
- Credential dates as alerts. Growth OS is built to flag secret rotation and reauthorization deadlines weeks ahead.
- Versions tracked. It is built to turn deprecations into planned releases before removal dates.
Growth OS is built to apply the same approach to other marketplace connections where their APIs allow it; Ecomsellertool has built integrations for 20+ marketplaces. To connect an AI assistant such as Claude to SP-API, see our guide to an SP-API MCP server; if you are building a tool with AI coding assistants, read what breaks when you build Amazon seller tools with AI; and before giving an agency or app access, see how to give an agency access to Seller Central safely. You keep your accounts, your data and the custom code we build; the Growth OS base is licensed to you.
Where should you start?
If your team still exports Seller Central reports to answer stock or cash questions, start with the free 24-hour diagnostic in the Ops Gap Diagnostic: connect Amazon with Login with Amazon, no password shared, and get a report of what is going wrong within 24 hours of connecting, on business days. We only read data; we never change listings, prices, stock or ads. The paid Deep Diagnostic covers every channel you sell on. To register your own app first, read how to register for Amazon SP-API, or see the base system in Growth OS.
Frequently asked questions
Do I need a developer account to use Amazon SP-API?
Yes. You complete a developer profile in Seller Central or in Solution Provider Portal, and Amazon reviews it against its Acceptable Use and Data Protection policies before granting access. Registering in Solution Provider Portal does not need a professional selling account, but building a private seller app from Seller Central does, because individual accounts are not eligible. The Primary User has to complete registration and self-authorize the app.
What is the difference between a private and a public SP-API app?
A private app integrates only your own company, is self-authorized, and is capped at 10 self-authorizations. A public app is authorized by other sellers through OAuth, and public developers are required to list it in the Selling Partner Appstore. Until it is listed, a seller app is capped at 25 OAuth authorizations; once listed, OAuth authorizations are unlimited.
How do I get orders and reports from SP-API?
Orders come from the Orders API, where v2026-01-01 replaces the v0 operations being removed in March 2027. Reports are asynchronous: you request one with createReport, wait for the REPORT_PROCESSING_FINISHED notification or poll its status, then download the document.
Does SP-API include Amazon advertising data?
No. Ad campaigns are managed through the separate Amazon Ads API, which has its own access requirements. Margin-aware ad work joins the two: sales, fees and stock from SP-API, spend and clicks from the Ads API.
How we research, fact-check and compare: our editorial standards. Spot an error? Email hello@ecomsellertool.com and we will correct it.
