Finances pagination nextToken: migration guide and scanner checklist

Official status

Amazon documentation lists Unsafe listTransactions nextToken handling 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.

Empty page with nextToken example

A listTransactions page can be empty and still be incomplete. The loop must stop only when nextToken is null, and every follow-up request must include the same arguments that produced the token.

const baseArgs = { postedAfter, postedBefore, marketplaceId };
let response = await listTransactions(baseArgs);
while (true) {
  collect(response.transactions ?? []);
  if (!response.nextToken) break;
  response = await listTransactions({ ...baseArgs, nextToken: response.nextToken });
}

Removed resource and replacement

What breaks

Before/after example

The example is intentionally small so the migration shape is visible in a code review.

Before:
if (response.transactions.length === 0) return done;

After:
while (response.nextToken) response = await listTransactions({ postedAfter, postedBefore, nextToken: response.nextToken });

Scanner detection

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.