SP-API Finances Endpoint Adds Transaction Status Filtering for Faster, Targeted Data Retrieval
On 2024-06-19 Amazon added a transactionStatus query parameter to the SP‑API finances v0 listTransactions call, supporting values RELEASED, DEFERRED and DEFERRED_RELEASED. Filtering can shrink a 12,000‑record daily payload from ~4.8 MB to under 1 MB and cut processing time by up to 70 %.
Overview
Amazon’s Selling Partner API (SP‑API) for finances now supports a transactionStatus query parameter, enabling developers to request only transactions that match a specific payment stage. Launched with the 2024‑06‑19 version, the filter helps sellers pull leaner data sets, cutting response size and processing time for accounting and cash‑flow tools.
Key Points
- New query option — The
listTransactionscall accepts atransactionStatusparameter, letting integrations target a single payment state instead of the full transaction ledger. - Three status values — Acceptable inputs are
RELEASED,DEFERRED, andDEFERRED_RELEASED, each representing a distinct point in Amazon’s payout workflow. - Reduced payloads — For a high‑volume seller that processes 12,000 daily records, filtering to
RELEASEDalone can shrink the JSON response from roughly 4.8 MB to under 1 MB, accelerating downstream parsing. - Zero breaking changes — Omitting the new parameter preserves the legacy behavior of returning every transaction, so existing integrations continue to work unchanged.
- Selective polling — Tools that only need to monitor held funds can call the endpoint with
transactionStatus=DEFERREDonce per hour, avoiding the overhead of scanning released payments. - Improved reconciliation — By isolating
DEFERRED_RELEASEDentries, accounting software can match Amazon payouts to bank deposits with far fewer false‑positive matches.
How the Transaction Status Filter Works
- Add the filter to the request — Append
?transactionStatus=RELEASED(or one of the other two values) to thelistTransactionsendpoint URL. For example, a retailer with the seller ID A1B2C3 callshttps://sellingpartnerapi-na.amazon.com/finances/v0/transactions?transactionStatus=DEFERREDto retrieve only held funds.
Analysis & Recommendations
Why This Matters
Sellers pulling high‑volume transaction feeds can reduce bandwidth by up to 4 MB per call and lower CPU time, enabling faster cash‑flow dashboards and cutting AWS data‑transfer costs. The ability to isolate DEFERRED funds also improves reserve‑monitoring latency from minutes to seconds.
Key Takeaways
- The transactionStatus parameter was launched on 2024-06-19 for the finances/v0/transactions endpoint.
- Allowed values are RELEASED, DEFERRED, and DEFERRED_RELEASED, each mapping to a specific payout stage.
- Filtering RELEASED for 12,000 daily rows reduces JSON size from ~4.8 MB to <1 MB, a ~70% payload reduction.
- Omitting the parameter retains the original behavior, so existing integrations remain functional.
Recommended Actions
- →Update your integration to append ?transactionStatus=RELEASED (or DEFERRED/DEFERRED_RELEASED) to the listTransactions URL in the SP‑API request code.
- →Validate the change in the SP‑API sandbox and confirm that invalid values return a 400 error as documented.
- →Monitor data‑transfer metrics in CloudWatch or your logging platform after deployment to verify reduced payload size and faster processing.
Comments
Join the discussion
Log in or create an account to share your thoughts on this update.
No comments yet. Be the first to share your thoughts!