1. What actually changes
Two things, and the second is the one that bites.
The shape of the data changes. Finances v0 returned typed event lists — ShipmentEventList, RefundEventList, ServiceFeeEventList, AdjustmentEventList and so on — each a different structure. Finances 2024-06-19 (listTransactions) returns one flat transactions[] array, where each item carries a transactionType and a uniform breakdown structure. So you stop switching on which list a line came from and start switching on transactionType.
The access pattern changes. v0 let you pull events by order (listFinancialEventsByOrderId) and by group (listFinancialEventsByGroupId). 2024-06-19 has one query: a posted-date window (postedAfter/postedBefore), and you filter the results yourself using each transaction's relatedIdentifiers[]. There is no by-order and no by-group endpoint anymore.
AmazonOrderId, it will silently drop those lines on 28 Aug and your totals will drift by amounts you can't find by hand. That's section 4.
2. Endpoint mapping
| Finances v0 (removed 28 Aug 2026) | Finances 2024-06-19 |
|---|---|
GET /finances/v0/financialEventslistFinancialEvents | GET /finances/2024-06-19/transactionswindowed by postedAfter/postedBefore |
GET /finances/v0/orders/{orderId}/financialEventslistFinancialEventsByOrderId | listTransactions, then filter where relatedIdentifiers[] has ORDER_ID = {orderId} |
GET /finances/v0/financialEventGroupslistFinancialEventGroups | No group-list endpoint. Take payout boundaries from the settlement report, or window by postedDate |
GET /finances/v0/financialEventGroups/{id}/financialEventslistFinancialEventsByGroupId | listTransactions windowed to that group's date range; match settlement-id ↔ group at the payout level |
Paging is unchanged in spirit: follow nextToken until it's absent. The 2024-06-19 call also accepts marketplaceId and transactionStatus filters — use the latter (see edge case 2).
3. The field map
Conceptual mapping from a v0 event to a 2024-06-19 transaction. The exact nesting depends on the transaction type, but these are the anchors:
| v0 concept | 2024-06-19 location | Note |
|---|---|---|
Which event list (ShipmentEvent, RefundEvent…) | transaction.transactionType | Classify by type instead of by list name |
AmazonOrderId | relatedIdentifiers[] → item where relatedIdentifierName = "ORDER_ID" | May be absent — see edge case 1 |
SellerSKU / shipment / adjustment ids | relatedIdentifiers[] (SHIPMENT_ID, ADJUSTMENT_ID…) and items[].contexts[] | Identifiers are a typed list now |
PostedDate | transaction.postedDate | Your windowing key |
ChargeComponent (Principal, Tax…) | breakdowns[] / items[].breakdowns[] | Nested amount breakdowns |
FeeComponent (Commission, FBA fees…) | breakdowns[] with negative amounts | Signs matter — sum them, don't abs() |
Amount { CurrencyCode, CurrencyAmount } | totalAmount { currencyCode, currencyAmount } and per-breakdown amounts | Group by currency (edge case 5) |
| Marketplace | sellingPartnerMetadata.marketplaceId / marketplaceDetails | — |
FinancialEventGroupId | Not on the transaction directly | Reconcile via settlement / date window |
totalAmount (respecting sign and currency) should tie to the payout the settlement report declares. If it doesn't, it's almost always one of the four things below — not the field map.4. The reconciliation edge cases (where the money hides)
1 — Lines with no order id
Service fees, subscription charges, storage fees and some adjustments reference only a payout/group, never an AmazonOrderId. In 2024-06-19 they appear as transactions whose relatedIdentifiers[] has no ORDER_ID. Reconcile purely by order and they vanish — this is the single most common reason a total won't match after the cut-over.
2 — Deferred vs Released
Honour transactionStatus. Reserves and deferred amounts (Deferred) are not yet in the payout; counting them as Released double-books money that hasn't paid out.
3 — Reconcile the payout total first
There's no 1:1 row match between transactions and the settlement flat-file. Match at the payout/group total first (settlement-id ↔ event group), then drill into line items. Row-first reconciliation drifts by cents you'll never find manually.
4 — Currency splits
A single window can contain more than one currency. Group by currencyCode before you compare — a mixed-currency sum is meaningless.
5. Migration checklist
grep -rn "finances/v0" .across the whole codebase — know your exposure (or paste it into the scanner).- Replace each v0 call per the endpoint table; switch reporting logic from event-list-name to
transactionType. - Handle the no-order-id lines explicitly.
- Respect
transactionStatus(Released vs Deferred). - Add a reconciliation assertion: transactions grouped by payout must tie to the settlement total, per currency.
- Add retries + a log that surfaces every divergence — no silent syncs.
- Validate against a real payout before 28 Aug.
Want it migrated and reconciled before the 28th — in writing, no calls?
I run five SP-API integrations in production, and Amazon's own developer team validated my reconciliation approach publicly (GitHub issue #5353). Send one settlement and your v0 exposure; the €90 audit tells you exactly where it breaks, and comes off the price if you go done-for-you.