Migration assurance
listTransactions breakdowns null
listTransactions breakdowns null is a real Amazon SP-API troubleshooting query. This page explains the likely cause, how to check code evidence, how to validate the fix, and where API Migration Guard can catch the pattern.
- Target keyword: listTransactions breakdowns null
- Removed: listTransactions transaction/items breakdowns
- Replacement: handle null breakdown arrays and reconcile transaction-level breakdowns explicitly
- Removal date: August 27, 2027
TL;DR
| Deprecated item | Removal date | Replacement | Migration risk | Scanner detection |
|---|---|---|---|---|
| listTransactions transaction/items breakdowns | August 27, 2027 | handle null breakdown arrays and reconcile transaction-level breakdowns explicitly | Null breakdown handling can erase reimbursements or adjustments from finance reconciliation. | AMZ-FIN-BREAKDOWN-001 |
Official status
Amazon documentation lists listTransactions transaction/items breakdowns 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. |
Quick answer
listTransactions breakdowns null usually means the response contains transactions where some breakdown arrays are null even though totals still need reconciliation. The fastest check is: Inspect transactionType, totalAmount, transaction-level breakdowns and item-level breakdowns separately.
| Symptom | Fast check | Likely owner |
|---|---|---|
| the response contains transactions where some breakdown arrays are null even though totals still need reconciliation. | Inspect transactionType, totalAmount, transaction-level breakdowns and item-level breakdowns separately. | API/platform owner plus finance, orders or support reviewer as applicable. |
Why this happens
This troubleshooting page is tied to listTransactions transaction/items breakdowns, not a generic SP-API failure.
| Cause | What to verify |
|---|---|
| Cause 1 | The parser assumes every transaction item has breakdowns. |
| Cause 2 | Some reimbursement or adjustment transactions expose detail at transaction level instead of item level. |
| Cause 3 | Null breakdowns are converted to zero without preserving the totalAmount. |
| Cause 4 | The reconciler treats missing arrays as schema failure instead of a valid shape to classify. |
How to detect it in your code
Search the source, scheduled jobs, generated clients, report configuration and sample fixtures before assuming the issue is only live data.
const breakdowns = txn.breakdowns ?? [];
const itemBreakdowns = (txn.items ?? []).flatMap(item => item.breakdowns ?? []);Fix checklist
- Update parser code to accept null or missing breakdown arrays.
- Preserve totalAmount even when item breakdowns are null.
- Classify transaction-level breakdowns separately from item-level ones.
- Add FBA reimbursement and adjustment samples.
- Reconcile totals with deterministic decimals.
- Re-scan source for direct breakdowns.length assumptions.
Migration risk
Null breakdown handling can erase reimbursements or adjustments from finance reconciliation.
| Production surface | Risk if ignored |
|---|---|
| Accounting/order/support workflow | Null breakdown handling can erase reimbursements or adjustments from finance reconciliation. |
| Release gate | The migration can look complete while the runtime job still fails or silently loses data. |
| Audit evidence | Without a preserved sample, reviewers cannot distinguish an accepted limitation from a migration bug. |
How API Migration Guard checks it
API Migration Guard scans for exact operation names, report type constants, endpoint strings, query parameters, parser assumptions and token/window loops. Paid reports add file-level findings, remediation notes, sample validation steps, CSV/JSON/SARIF exports and an evidence package.
| Rule | Evidence | Validation |
|---|---|---|
| AMZ-FIN-BREAKDOWN-001 | listTransactions transaction/items breakdowns | Re-scan source for direct breakdowns.length assumptions. |
Removed resource and replacement
| Old resource | Replacement | Deadline | Validation outcome |
|---|---|---|---|
| listTransactions transaction/items breakdowns | handle null breakdown arrays and reconcile transaction-level breakdowns explicitly | August 27, 2027 | Null breakdown handling can erase reimbursements or adjustments from finance reconciliation. |
What breaks
| Area | Breakage |
|---|---|
| Code pattern | Runtime or source evidence points at listTransactions transaction/items breakdowns. |
| Payload or schema | the response contains transactions where some breakdown arrays are null even though totals still need reconciliation. |
| Permission or data access | The parser assumes every transaction item has breakdowns. |
| Pagination, status or field mapping | The reconciler treats missing arrays as schema failure instead of a valid shape to classify. |
Before/after example
The example is intentionally small so the migration shape is visible in a code review.
Before:
const breakdowns = txn.breakdowns ?? [];
const itemBreakdowns = (txn.items ?? []).flatMap(item => item.breakdowns ?? []);
After:
// Fix path: handle null breakdown arrays and reconcile transaction-level breakdowns explicitly
// Validate with API Migration Guard, sample evidence and a re-scan.Scanner detection
| Rule ID | Severity | Evidence pattern | False positive condition | Validation step |
|---|---|---|---|---|
| AMZ-FIN-BREAKDOWN-001 | HIGH for runtime error evidence; BLOCKER when tied to removed resources | listTransactions transaction/items breakdowns | Documentation, comments, generated clients or test fixtures can require manual review. | Update parser code to accept null or missing breakdown arrays. |
Migration checklist
- Update parser code to accept null or missing breakdown arrays.
- Preserve totalAmount even when item breakdowns are null.
- Classify transaction-level breakdowns separately from item-level ones.
- Add FBA reimbursement and adjustment samples.
- Reconcile totals with deterministic decimals.
- Re-scan source for direct breakdowns.length assumptions.
Common mistakes
- Treating listTransactions breakdowns null as a transient Amazon outage before checking the request shape.
- Changing code without preserving a sample request, response and report evidence.
- Closing the ticket without re-scanning source and validating the affected sample.
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
How do I fix listTransactions breakdowns null?
Confirm the request evidence, apply the handle null breakdown arrays and reconcile transaction-level breakdowns explicitly path, validate the sample and re-scan.
Can API Migration Guard detect listTransactions breakdowns null?
It detects source patterns related to AMZ-FIN-BREAKDOWN-001 and shows evidence, remediation notes and validation steps.
Does the free scan call Amazon?
No. It scans uploaded or pasted source statically and can validate pasted samples without Amazon credentials.
When should this become a paid report?
When the free scan finds matching production evidence and the team needs file-level findings, SARIF, CSV or handoff artifacts.
Official sources
Validate listTransactions breakdowns null in your source
Run a static scan, review the sample report shape, then unlock the detailed migration report when the evidence is useful.