On 28 August 2026, Amazon removes the Finances API v0 event operations — listFinancialEvents, listFinancialEventsByGroupId, listFinancialEventsByOrderId. If your integration still reads financial data through them, it stops working that day. The replacement is Finances v2024-06-19 listTransactions.
Most write-ups stop at "swap the endpoint." That's not where migrations break. They break in reconciliation, and the failure is silent — your code runs, your dashboard loads, and your numbers are quietly wrong. Here is the exact shape of it.
One order, one payout
Principal +41.00
Commission -6.15
FBA Inbound Defect Fee -3.30 <- no AmazonOrderId
------------------------------------
Payout 31.55
The first two lines carry an AmazonOrderId. The third — an FBA fee — does not. Inbound fees, storage fees, and reserve adjustments frequently arrive with no order attached at all.
Now look at what a "clean" migration usually does: it pulls transactions, groups by order id, and sums. The moment you GROUP BY order_id (or inner-join on it), that -3.30 has nowhere to go. It vanishes. Your payout reconciles to 34.85 instead of 31.55, and nothing errors. Off by €3.30 on one order — multiply by a catalogue, then by a month.
Three things that actually change
1. Fees with no order are first-class rows, not errors. Treat a null AmazonOrderId as a valid state. If your schema makes order id non-nullable on financial rows, that's the bug.
2. Grouping is gone. listTransactions won't hand you pre-grouped events the way listFinancialEventsByGroupId did. To reassemble a group, query with relatedIdentifierName=FINANCIAL_EVENT_GROUP_ID; for an order, relatedIdentifierName=ORDER_ID.
3. Don't reconcile the payout with the API. Reconcile payout-level against the settlement report (the flat file); use the Finances API for order-level attribution. They answer different questions and have different cut-offs. Using one for both is how the totals drift.
The verification that catches it
Pick a past settlement period whose payout you already know. Run it through the new path and assert:
sum(all rows, including AmazonOrderId === null) === known_payout_total
to the cent. If it's short by a fee amount, you dropped unassociated fees. If it's off by ~2x on some rows, you double-counted on a retry. If it's high by a refund, you flipped a sign. Ship behind a flag and run old + new in parallel for one settlement cycle before deleting the v0 path.
Not sure this touches you? I built a free scanner — paste your code, it runs entirely in your browser (nothing is uploaded), and it tells you if you still call the v0 operations: https://claude.ai/code/artifact/cba38875-a9f8-4405-b647-e6c83aa366bc
I run five Selling Partner API accounts in production, including a settlement reconciliation service — Amazon's Developer Services team validated this reconciliation approach in their repo (issue #5353). I packaged the working listTransactions client, the v0→new mapping, the reconciliation guide and the cut-over checklist as a kit: https://barretovibes004.gumroad.com/l/cpxxpe
