feat(statements): balance changes and statement delivery confirmation

[ls-bolt]

This PR has been claimed. The active PR is now #1079.

Summary

Adds the two operations a platform needs to build and evidence a Regulation E periodic statement for an internal account, under a new Periodic Statements tag.

• GET /internal-accounts/{id}/balance-changes — one row per change to the account's balance in a half-open window [from, to), ordered by when the money moved, with the window's openingBalance and closingBalance in the same response. The balances describe the window rather than the page, so the identity openingBalance + Σ(data[].amount) == closingBalance holds across all pages. Paginated with limit / cursor.
• POST /internal-accounts/{id}/statement-confirmations — records that a period's statement was delivered to the customer. Idempotent; the stored time is the first delivery.

New error codes:

• 409 BALANCE_NOT_YET_FINAL — card settlement for a window boundary has not closed, so the figures could still change. Retry once settled.
• 422 PERIOD_NOT_REPORTABLE — the window cannot be reported; retrying will not change that.

transactionId on a balance change groups the lines of one movement on a statement. It is documented as not being a Transaction id, since it does not resolve through GET /transactions/{transactionId}.

Changes

• openapi/paths/internal_accounts/internal_accounts_{id}_balance-changes.yaml, …_statement-confirmations.yaml — new operations
• openapi/components/schemas/internal_accounts/ — BalanceChange, BalanceChangeListResponse, ConfirmStatementDeliveryRequest, StatementDelivery
• openapi/components/schemas/errors/Error409.yaml, Error422.yaml — new codes in both the description table and the enum
• openapi/openapi.yaml — tag and path refs
• .stainless/stainless.yml — customers.list_balance_changes, customers.confirm_statement_delivery, and the four models, alongside the existing internal-account methods
• openapi.yaml, mintlify/openapi.yaml — regenerated

Test plan

• make build bundles cleanly; openapi.yaml and mintlify/openapi.yaml are identical
• make lint passes: Redocly valid, Spectral 0 errors, and no warnings or infos on any added path or schema (existing repo-wide findings unchanged)
• Nullable timestamps use anyOf with type: 'null', matching the repo's OpenAPI 3.1 convention

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Sep 25, 2026 11:21pm UTC
grid-flow-builder	Ignored	Preview	Sep 25, 2026 11:21pm UTC
grid-wallet-demo	Ignored	Preview	Sep 25, 2026 11:21pm UTC

[ls-bolt]

@greptile review

[lightspark-bot]

• feat(statements): balance changes and statement delivery confirmation #1078 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Confidence Score: 4/5

[Low risk] Documents two new API endpoints in specification files.

The plan appears safe to merge, with a non-blocking pagination clarification recommended before implementing the specification.

Findings

1.  Reconciliation ignores pagination ▶

Fix with agent prompt

### Issue 1
docs/plans/2026-09-25-periodic-statements-spec.md:58
The plan says opening and closing balances cover the whole window, but `data` contains only one page. When `hasMore` is true, summing that page will generally not reconcile the balances and could make readers mistake a valid response for an error. Specify that the sum includes every page.

```suggestion
  identity `openingBalance + Σ(data[].amount across all pages) == closingBalance`, the
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR adds a plan for a periodic-statement balance-change feed and delivery confirmation; it does not yet change the OpenAPI specification.

• Clarify the planned reconciliation formula for paginated responses.

_{Reviews (1) · Last reviewed commit: "plan: periodic statements balance change..."}

[greptile-apps]

Reconciliation ignores pagination The plan says opening and closing balances cover the whole window, but data contains only one page. When hasMore is true, summing that page will generally not reconcile the balances and could make readers mistake a valid response for an error. Specify that the sum includes every page.

Suggested change

	identity `openingBalance + Σ(data[].amount) == closingBalance`, the
	identity `openingBalance + Σ(data[].amount across all pages) == closingBalance`, the

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/plans/2026-09-25-periodic-statements-spec.md
Line: 58

Comment:
**Reconciliation ignores pagination** The plan says opening and closing balances cover the whole window, but `data` contains only one page. When `hasMore` is true, summing that page will generally not reconcile the balances and could make readers mistake a valid response for an error. Specify that the sum includes every page.

```suggestion
  identity `openingBalance + Σ(data[].amount across all pages) == closingBalance`, the
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[ls-bolt]

Right, the rollups bound the window and data is one page. The plan now states the identity across all pages, and the spec text will say the same.

---

🤖 spectral-anchorage-19(#19) | Feedback

[ls-bolt]

⚡ Review ledger

Round 1

1. greptile — reconciliation ignores pagination → FIXED in the plan: the identity is stated across all pages of data, and the tag and BalanceChangeListResponse descriptions will say so.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Sep 25, 2026, 11:22 PM