Amazon removes the SP-API Finances v0 event operations on 28 August 2026. Most teams will do the migration the obvious way — swap /finances/v0/... for listTransactions (2024-06-19), map the fields, ship it, green tests. And then, a settlement or two later, the payout stops tying out by an amount nobody can find by hand.
I run five Selling Partner API integrations in production, including a settlement reconciliation service, and Amazon's own developer team validated my reconciliation approach publicly (GitHub issue #5353). Here are the three bugs that pass every "it works" check and quietly break the money — with what to test before the 28th.
The migration everyone does (and why it's only half)
v0 returned typed event lists — ShipmentEventList, RefundEventList, ServiceFeeEventList, AdjustmentEventList… each a different shape. listTransactions returns one flat transactions[] where each item carries a transactionType. So the mechanical part is: stop switching on which list a line came from, start switching on transactionType. Instead of v0's separate by-order / by-group operations, you now pass a single relatedIdentifierName + relatedIdentifierValue on listTransactions — the two that currently support filtering are FINANCIAL_EVENT_GROUP_ID and ORDER_ID — or you window by postedAfter/postedBefore. Each transaction still carries a relatedIdentifiers[] array you classify on.
That part is easy and every quote covers it. The part that costs money is reconciliation, and it fails in three specific places.
Bug 1 — the lines with no order id
Service fees, subscription charges, storage fees and some adjustments reference only a payout/group — never an AmazonOrderId. In listTransactions they show up as transactions whose relatedIdentifiers[] has no ORDER_ID.
If your reporting or accounting sync keys off order id (most do — it's the natural join), those lines silently drop the day v0 goes dark. Your per-order numbers look fine. Your payout total is short by exactly those fees, and because there's no order to trace them to, you can burn a day looking for cents.
Test: pull one settlement, sum every transaction's totalAmount (respecting sign), and confirm it ties to the declared payout — including the no-order-id lines. If your reconciliation only sums order-linked rows, this is where it drifts.
Bug 2 — Deferred counted as Released
listTransactions returns a transactionStatus. Reserves and deferred amounts (Deferred) are not yet in the payout. Count them as Released and you double-book money that hasn't actually paid out — the report looks richer than the bank deposit.
Test: filter by transactionStatus and reconcile Released against the deposit; keep Deferred in a separate bucket. If a single flat sum matches "close enough," you're probably mixing the two.
Bug 3 — reconciling row-by-row instead of payout-first
There is no 1:1 row match between listTransactions output and the settlement flat-file. Teams that try to match line-by-line chase rounding ghosts forever.
The order that actually works: match the payout/group total first (settlement-id ↔ financial event group), confirm it ties, then drill into line items. And group by currencyCode before you compare — a single window can hold more than one currency, and a mixed-currency sum is meaningless.
What to do this week
- Grep for every
finances/v0call and switch reporting from event-list-name totransactionType. - Handle the no-order-id lines explicitly.
- Honour
transactionStatus(Released vs Deferred). - Assert: transactions grouped by payout tie to the settlement total, per currency.
- Validate against a real payout, not a demo, before 28 Aug.
Two free tools + the field map
I put the full v0 → listTransactions field map and these edge cases on one page, no sign-up:
- Field-mapping guide (free): https://proficientstack.com/sp-api-guide.html
- 30-second scanner — paste your integration, it flags every v0 call that breaks and shows the replacement, in your browser: https://proficientstack.com/sp-api-scanner.html
- Settlement reconciler — paste a settlement flat-file, it sums the lines against the payout and flags the no-order-id lines: https://proficientstack.com/sp-api-reconciler.html
If you'd rather just have it migrated and reconciled before the 28th — in writing, no calls — that's what I do; there's a paid audit and a done-for-you option on the same site. But the tools are free and will tell you where you stand in a minute.
12 days. The migration is the easy half. The reconciliation is where the money hides.
Amazon settlement not reconciling against the transactions behind it? I run a fixed-price reconciliation audit — settlement vs Finances API, never double-counted. The approach the SP-API team validated publicly in issue #5353.
