Skip to content

Blog

Amazon SP-API integration: a practical guide for sellers

What an Amazon Selling Partner API integration involves: authorization, rate limits, notifications, reports, listings and restricted data, and the mistakes that make integrations break.

· by Iyasin Arafat, Founder, Artisan Dojo

The Amazon Selling Partner API (SP-API) is how software talks to Seller Central and Vendor Central: orders, inventory, prices, listings, reports and notifications. If your ERP, warehouse system or internal tools need Amazon data, an SP-API integration is the way to get it.

This guide covers what such an integration actually involves, and the mistakes we most often see when we are asked to fix one.

What you can do with SP-API

Most seller integrations use a handful of API sections:

  • Orders: fetch new and updated orders, including FBA and merchant-fulfilled (FBM) orders.
  • Fulfillment and shipping: confirm shipments and send tracking numbers back to Amazon for FBM orders.
  • Listings Items and Product Type Definitions: create and update listings, using Amazon's JSON schemas to validate attributes before submitting.
  • Feeds: submit changes in bulk, for example price and quantity updates across thousands of SKUs.
  • Reports: download inventory, sales, fee and settlement data as files.
  • Notifications: receive events such as order changes or finished reports instead of asking for them repeatedly.

Step 1: Register an application and get authorized

Before any code runs, you need a developer registration and an application in Seller Central.

  • A private application is used only for your own seller account. It is the usual choice for a seller connecting Amazon to their own ERP.
  • A public application is offered to other sellers, for example a SaaS tool, and goes through a stricter review.

Your application requests roles, such as Inventory and Order Tracking, Pricing or Product Listing. Request only the roles you need, because each one is reviewed.

Authorization uses Login with Amazon (LWA). A private application can self-authorize and receive a long-lived refresh token. Your integration exchanges it for a short-lived access token (valid for about an hour) and sends that with every request. Store the refresh token and client secret in a secrets manager, never in code.

Step 2: Respect rate limits from day one

Every SP-API operation has its own usage plan: a steady rate of requests per second and a burst allowance. When you exceed it, Amazon answers with HTTP 429.

The integrations that break most often are the ones that ignore this. In practice:

  • Queue requests per operation and pace them to the documented rate.
  • Retry 429 and 5xx responses with exponential backoff and jitter.
  • Read rate-limit headers when Amazon sends them, because some limits differ per account.
  • Use bulk options (feeds and reports) instead of one call per SKU wherever possible.

Step 3: Use notifications instead of constant polling

A common anti-pattern is polling the Orders API every minute, all day. It wastes quota and still reacts late.

The Notifications API can push events, such as order status changes, listing status changes, offer changes and finished reports, to an Amazon SQS queue or Amazon EventBridge. Your integration consumes the queue and only calls the API when something actually happened. Keep a slower scheduled sync as a safety net for missed events.

Step 4: Get order data into your ERP reliably

Order import looks simple and causes most of the real-world problems. Things to get right:

  • Fetch orders by last updated time, not creation time, so you also catch changes and cancellations.
  • Follow pagination until the end of the result set.
  • Make the import idempotent: importing the same order twice must not create two orders in your ERP. Use the Amazon order ID as a unique key.
  • Buyer name, address and similar details are restricted data. They need the right roles and a Restricted Data Token for the request, and must be stored and deleted according to Amazon's data protection policy.
  • For FBM orders, send the shipment confirmation with tracking back promptly, as late confirmations affect your account health metrics.

Step 5: Keep stock and prices in sync

Your ERP or warehouse system should be the single source of truth for stock. The integration pushes changes to Amazon, not the other way round.

  • Send only changes (deltas) frequently, plus a full reconciliation on a schedule.
  • Keep a safety buffer for items sold on several channels, so a sale on one marketplace does not oversell on Amazon before the next update.
  • For thousands of SKUs, use the JSON listings feed or batched updates instead of individual calls.

Step 6: Listings and catalog data

Amazon's listing model is driven by product types, each with a JSON schema of required and optional attributes. The Product Type Definitions API returns these schemas, so your integration can validate data before submitting it, instead of finding out from errors afterwards.

Amazon has been retiring older XML and flat-file listing feeds in favour of the Listings Items API and JSON-based feeds. If your integration still relies on the old formats, plan the migration before the deadline rather than after it.

Step 7: Reports for finance and analytics

Settlement, fee, inventory and sales data come from the Reports API. The flow is asynchronous: request a report, wait for it to finish (ideally via a notification), then download the document, which may be compressed. Load the result into your database or BI tool on a schedule.

Step 8: Monitoring and maintenance

Amazon changes SP-API regularly: new versions, deprecated operations, new required attributes. A working integration needs:

  • Logging of every failed request with the Amazon request ID.
  • Alerts when orders stop arriving, error rates rise or a sync falls behind.
  • Someone who reads Amazon's deprecation notices and updates the code in time.

Common mistakes we fix

  1. One API call per SKU, hitting rate limits every day.
  2. Polling instead of notifications.
  3. Order import that creates duplicates after a retry.
  4. Credentials hard-coded in scripts.
  5. No alerting, so problems are found by customers.
  6. Old code ported from MWS without redesigning for SP-API's model.

When to get help

If your integration keeps breaking, or you are starting a new one and want it built properly the first time, we can help. We usually start with an Integration Health Check: a review of your current setup and a prioritized plan of what to fix and what it will take. See our Amazon SP-API integration service or describe your project below.

Need help with this?

Describe your project. Get a reply from an engineer.

Which marketplaces or platforms are involved?
What do you need?
How should we get back to you?

We use your details only to reply to this inquiry. See our privacy policy.

MessageRequest a call