Amazon SP-API order notifications: how apps learn that you have a new order

What the Selling Partner API is, and what it replaced

Every serious tool that touches your Amazon account, from repricers to accounting exports to an order alert app, talks to the same place: the Selling Partner API, usually shortened to SP-API. An app only ever sees what you have authorised it to see.

It is also fairly new. Its predecessor was Amazon Marketplace Web Service, MWS for short. Amazon announced the end of it on the Seller Forums: "SP-API will fully replace MWS, and we are migrating developers to SP-API as we work to deprecate MWS", with the hard date that MWS "will no longer be available after March 31, 2024". If an older guide tells you to generate MWS keys, it is describing a system that no longer exists.

There is no single Amazon Seller Central API

People search for "Amazon Seller Central API" as though it were one thing. It is a family: an Orders API for orders, a Sales API for daily totals, a Reports API for the flat files you can also download by hand, a Notifications API for push messages, a Finances API for transactions. An order alert app touches three of them at most.

SP-API is also split by region. Europe, North America and the Far East are separate endpoints with separate authorisations, which is why an app asks you to connect once for Europe and again for North America if you sell in both. That is the technical reason behind the account structure in selling across several Amazon marketplaces.

What a seller grants when an app connects

Access is not a password. You land on a consent page on Amazon's own domain, you see which roles the app asks for, and you tap Confirm. Your login details never pass through the app.

Roles are the part worth reading. Amazon describes the one an order app needs like this: "The Inventory and Order Tracking role provides access to operations that analyze and manage inventory." It covers reading orders and subscribing to ORDER_CHANGE. Roles that expose buyer names and addresses are a separate, restricted category with a heavier review, and an alert app has no reason to ask for them.

Two facts sellers rarely hear. Authorisation is not permanent: Amazon states that "the selling partner must reauthorize your public application every 365 days, or anytime you add a role to your application". And you can end it in a minute in Seller Central under Apps and Services, Manage Your Apps. The full walkthrough is in how to connect an app to Seller Central safely.

ORDER_CHANGE: the message, and the queue behind it

Amazon's Notifications API offers roughly two dozen notification types. The one that matters for orders is ORDER_CHANGE: "The ORDER_CHANGE notification is sent whenever there is an important change in the order. Important changes include order status changes and buyer requested cancelations." An older type called ORDER_STATUS_CHANGE existed, and Amazon's own tutorial says it "have been deprecated" and tells developers to move to ORDER_CHANGE.

Delivery is where most people guess wrong. Amazon does not post to a webhook address of your choosing for this type. It writes into an Amazon SQS queue, a message queue the app operator sets up in its own cloud account and then allows Amazon to write to. Amazon's setup page lists ORDER_CHANGE among the types delivered this way, and adds a constraint that tells you something about the design: "Selling Partner API does not support delivery to FIFO queues. You must use Amazon SQS standard queues to receive notifications."

Standard queues can deliver a message more than once and out of order. That is normal, and it is why a careful app keeps a record of every notification id it has already handled. If an app ever plays the same cha-ching twice, this is usually where it went wrong.

What the payload contains, and what it leaves out

The message is compact and built around the order, not the item. Amazon is explicit: "If you have multiple order items in the order, you will receive consolidated payloads at the order level." One order with four products is one message with four entries inside it, not four alerts.

What is missing is the part sellers care about most. There is no order total, no item price, no ASIN and no product title. Amazon's solution architects describe ORDER_CHANGE as a trigger to fetch the full order from the Orders API rather than a replacement for it, so an app that shows you an amount has made a second call to get it.

That second call has a limit while the order is fresh. Amazon defines Pending as "The order has been placed but payment has not been authorized", and during that window "the getOrderItems operation does not return information about pricing, taxes, shipping charges, gift status or promotions". Pending usually clears in about half an hour, since "the fulfillable date of an order is usually 30 minutes after the order has been created". So any amount in the first minutes is an estimate. We show ours with a "≈" sign and update it quietly once Amazon releases the real number, for the reasons set out in what a Pending order means for a seller.

One field deserves a note: the payload includes a destination postal code, and Amazon's Data Protection Policy counts a postal code as personally identifiable information. An app that wants no buyer data on its servers throws that field away before anything is stored. Ours does.

Why FBA orders stay silent while they are Pending

This is the part that is not in the documentation, because we only found it by running the whole chain against our own seller account.

If push is your only channel, an FBA seller hears about a sale once payment is authorised, which on our account was hours after the buyer clicked buy, not seconds. That is why we use three layers, in the opposite order to the one most architecture diagrams suggest.

The third layer is not our invention. Amazon asks for it: "As a best practice, we recommend that you have a means to retrieve needed information in the event of an unexpected outage or delay in notification delivery." An app without a backup will quietly lose an order one day and never tell you. How the layers add up in wall clock time is covered in how fast an Amazon order alert can really be.

What this means when you are choosing an app

You do not need to read a line of code to judge an order alert app. Four questions separate the careful ones from the rest.

1. Which layers does it use? Push only is the cheapest to build and the one that goes quiet for FBA orders in Pending. Ask whether it also polls, and how often.
2. Does it count what it missed? A backup layer is only worth something if the result is visible. Our app shows a missed order count with a target of zero, and every alert shows how long it was in transit.
3. Which roles does it ask for? You see them on the consent page before you confirm. One read only role is enough. A request for buyer addresses on an alert app is a reason to stop.
4. What does it store? The payload contains a postal code, and Amazon treats that as buyer data. Ask whether it is discarded, and how fast everything goes when you disconnect.

If you are still weighing up whether you need a third party app at all, start with what the official Amazon Seller app does and does not send.