Name a statement receipt's period by its month

[ls-bolt]

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

Summary

• POST /internal-accounts/{id}/confirm-statement takes statementMonth (YYYY-MM) in place of periodStart, and StatementDelivery returns it the same way.
• A statement covers a calendar month, so the receipt names that month. The old field was a date that had to be the first of the month.
• Updated the endpoint's 400 text, the Periodic Statements tag description, and the statements guide example.
• GET /internal-accounts/{id}/balance-changes: the cursor description now says to send it unchanged with the same account, startDate and endDate as the page that issued it, and that it expires after 24 hours. The 400 text covers a cursor issued for another window, or one that has expired.

Compatibility

This changes the request and response shape of confirm-statement. The endpoint is new, and no integrator sends receipts yet.

Test plan

• make build, make lint-openapi: the spec bundles and lints clean (only pre-existing warnings).

Requested by @benwgold

[mintlify]

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

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Oct 8, 2026, 6:27 AM

[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	Oct 8, 2026 6:27am UTC
grid-flow-builder	Ignored	Preview	Oct 8, 2026 6:27am UTC
grid-wallet-demo	Ignored	Preview	Oct 8, 2026 6:27am UTC

[ls-bolt]

@greptile review

[github-actions]

⚠️ Breaking OpenAPI changes detected

oasdiff reports 2 error / 1 warning changes to openapi.yaml.
This PR will need approval from an API reviewer before merge.

Errors (2)

• POST /internal-accounts/{id}/confirm-statement — added the new required request property statementMonth [new-required-request-property].
• POST /internal-accounts/{id}/confirm-statement — removed the required property periodStart from the response with the 200 status [response-required-property-removed].

Warnings (1)

Show sample

• POST /internal-accounts/{id}/confirm-statement — removed the request property periodStart [request-property-removed].

---

Detected by oasdiff. Full report: job summary or the oasdiff-report artifact.

[lightspark-bot]

• Name a statement receipt's period by its month #1134 👈 (View in Graphite)
• main

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

[greptile-apps]

Confidence Score: 5/5

[Critical risk] Changes the public API contract for statement receipts.

The PR appears safe to merge; no actionable issues were found.

What we checked:

• Statement pages keep their dates: The example keeps the account path and dates fixed. It sends each nextCursor unchanged, so it follows the new paging instructions.

Summary

This PR names statement receipts with statementMonth in YYYY-MM form instead of periodStart.

• Updates the request, response, endpoint descriptions, and statement example.
• Documents that balance-change cursors belong to one account and date window and expire after 24 hours.
• Keeps the modular source and both published bundles aligned.

_{Reviews (2) · Last reviewed commit: "Say a balance-changes cursor is bound to..." · Reviewed by Greptile}