Migration assurance
listFinancialEventsByOrderId replacement: migration guide and scanner checklist
listFinancialEventsByOrderId replacement explains what replaces listFinancialEventsByOrderId, the removal date, the migration risks to validate, and how API Migration Guard detects the pattern.
- Target keyword: listFinancialEventsByOrderId replacement
- Removed: listFinancialEventsByOrderId
- Replacement: listTransactions with relatedIdentifierName=ORDER_ID
- Removal date: August 27, 2027
TL;DR
| Deprecated item | Removal date | Replacement | Migration risk | Scanner detection |
|---|---|---|---|---|
| listFinancialEventsByOrderId | August 27, 2027 | listTransactions with relatedIdentifierName=ORDER_ID | Order-specific reconciliation can miss transactions if identifier mapping is not validated. | AMZ-FIN-OP-001 |
Official status
Amazon documentation lists listFinancialEventsByOrderId as in-scope for this migration. Use the official source before code freeze because deadlines and replacement details can change.
Amazon Finances API v2024-06-19 reference Amazon SP-API deprecation schedule
Production Finances validation plan
Finances migration must protect accounting completeness. The validator evidence should be paired with a manifest that proves windows, nextToken pagination, recursive breakdowns and expected totals for representative close periods.
| Validation area | Production proof to collect |
|---|---|
| Date windows | Split requests into 180-day-or-smaller UTC windows and record the generated ranges. |
| Pagination | Continue on empty pages when nextToken exists and preserve postedAfter/postedBefore on every token request. |
| Breakdowns | Reconcile recursive amounts with deterministic decimals instead of floats. |
| Identifiers | Validate order, settlement and transaction identifiers against expected ledger joins. |
ORDER_ID filter proof
Order-level finance pages should prove the new filter is actually scoped to the requested order and not just post-filtered by application code. That matters for support refunds, chargeback checks and shipment reconciliation.
| Check | Expected evidence |
|---|---|
| Request filter | relatedIdentifierName=ORDER_ID and relatedIdentifierValue set to the exact Amazon order ID. |
| Page chain | Every nextToken request preserves the same related identifier arguments. |
| Result identity | Each returned transaction records a matching related identifier or an accepted manual exception. |
| Accounting parity | Order-level totals reconcile against the legacy event output for a sampled shipped/refunded order. |
Removed resource and replacement
| Old resource | Replacement | Deadline | Validation outcome |
|---|---|---|---|
| listFinancialEventsByOrderId | listTransactions with relatedIdentifierName=ORDER_ID | August 27, 2027 | Order-specific reconciliation can miss transactions if identifier mapping is not validated. |
What breaks
| Area | Breakage |
|---|---|
| Code pattern | Finances v0 event-list call or endpoint usage for listFinancialEventsByOrderId. |
| Payload or schema | listTransactions uses transaction objects, recursive breakdowns and Currency object amounts. |
| Permission or data access | Recent data and date-window behavior need operational validation before financial close. |
| Pagination, status or field mapping | Windows over 180 days can return empty results; nextToken pages must preserve the original arguments. |
Before/after example
The example is intentionally small so the migration shape is visible in a code review.
Before:
await finances.listFinancialEventsByOrderId(orderId);
After:
await finances.listTransactions({ relatedIdentifierName: 'ORDER_ID', relatedIdentifierValue: orderId });Scanner detection
| Rule ID | Severity | Evidence pattern | False positive condition | Validation step |
|---|---|---|---|---|
| AMZ-FIN-OP-001 | BLOCKER or HIGH depending on source evidence | listFinancialEventsByOrderId | Documentation, comments, generated clients or test fixtures can require manual review. | Replace the v0 financial-event call with listTransactions and preserve request arguments on token pages. |
Migration checklist
- Replace the v0 financial-event call with listTransactions and preserve request arguments on token pages.
- Split postedAfter..postedBefore ranges into 180-day-or-smaller UTC windows.
- Validate a request manifest and page samples in the Finances Reconciliation Validator.
- Compare recursive breakdown totals and duplicate transaction IDs before using the output for accounting.
Common mistakes
- Stopping on an empty transactions array while nextToken still exists.
- Sending a token-only follow-up request without original listTransactions arguments.
- Flattening recursive breakdown totals with floats instead of deterministic decimals.
Sample report preview
The public sample report shows the same evidence shape used by paid reports: rule ID, severity, file location, redacted evidence, migration mapping, validation step and quality gate.
FAQ
What replaces listFinancialEventsByOrderId replacement?
listTransactions with relatedIdentifierName=ORDER_ID
Why does the 180-day window matter?
Amazon can return an empty response when the postedAfter..postedBefore range is more than 180 days.
Can a sample prove every finance total?
No. It proves the supplied pages and manifest reconcile within tested scope; production close still needs staged validation.
Official sources
Validate listFinancialEventsByOrderId replacement in your source
Run a static scan, review the sample report shape, then unlock the detailed migration report when the evidence is useful.