Statements and tax documents
A statement is the ledger's entries for one account and one month, issued once as an immutable PDF and delivered by email notice or on paper. The same cycle takes backup withholding, which feeds the year's 1099-INT figures.
What a statement is built from
GET /accounts/{id}/transactions returns every ledger entry on the account as a line with its date, kind, description, debit_amount or credit_amount, running balance_amount and journal_id. A period statement is the same lines for one month, named YYYY-MM, with opening_amount and closing_amount, the interest earned and paid, apy_earned_percent, and overdraft and returned-item fee totals for the period and the year to date. Once the ledger has sealed the month, the statement is built from the ledger's statement snapshot. Before that it is a preview.
The monthly cycle
Every deposit product has a statement_cycle of monthly. POST /accounts/cycles with a period works through the accounts a page at a time, at most 100 per call. For each account it assesses the product's monthly fees, records the interest credited, takes any backup withholding and saves the statement. It answers ledger.period_not_ready until the calendar month has ended and the ledger period is sealed. A failed account does not stop the page. It is listed at GET /accounts/cycles/periods/{period}/accounts?status=failed and rerun on its own.
Draft, issue, deliver
POST /accounts/{id}/statements/{period}/generationsbuilds the draft, andGET /accounts/{id}/statements/{period}reads it.POST /accounts/{id}/statements/{period}/issuesrenders the PDF and archives it with itssha256. It answersconflictwhile the period is still open or when no PDF renderer is configured. An issued statement never changes: a correction is reviewed by a second person and issued as a new version.POST /accounts/{id}/statements/{period}/deliverydispatches the issued version.
POST /accounts/statement-runs does the three steps for a page of accounts: a period, a limit of 1 to 100, and the flags issue and dispatch. Each item reports skipped, draft, issued, a delivery status, or failed with the problem code. Pass next back as after while has_more is true.
Paper and electronic delivery
Paper is the default. Electronic delivery needs the customer's own consent at PUT /accounts/{id}/statement-consent. The customer requests a challenge, downloads its PDF to show they can open one, and within 15 minutes sends the challenge_id and the PDF's code with action grant and accepted true. A staff or service token cannot grant consent. withdraw needs no challenge.
Delivery status | Meaning |
|---|---|
paper_pending | No current consent, or the email failed. The statement waits in the paper queue with channel paper. |
pending | An email notice is being sent. |
sent | The notification provider accepted the notice. The event behind it is accounts.statement.ready. |
simulated | The notice went to the simulated provider, as it does on the local stack. |
delivered, failed | Recorded afterwards as delivery evidence, with the provider_ref. A failed email moves the statement to the paper queue. |
GET /accounts/statement-deliveries lists deliveries by status.
Backup withholding and the W-9
A new customer has backup_withholding true, because no certified taxpayer identification number is on file. While it is true, the monthly cycle withholds 24% of the interest credited. POST /customers/{id}/tax-certifications records the form on file: a form of w9, w8ben or w8bene, tin_certified and received_at. A W-9 with a certified TIN lifts the withholding, and one without keeps it. A W-8BEN from a person or a W-8BEN-E from a business marks a foreign customer, whose interest is not withheld from until the form lapses at the end of the third calendar year after it was received.
1099-INT figures
GET /tax-forms/1099-int?year=2026 returns each customer's interest_amount and withheld_amount for the year and the form that applies: 1099-INT at $10.00 of interest or on any withholding, 1042-S for a customer on a W-8, and none below the threshold or for an IRA, HSA or IOLTA account. format=irs1220 returns the Forms 1099-INT as a Publication 1220 file, and format=irs1187 the Forms 1042-S as a Publication 1187 file. The route admits only staff who hold customers:tax:read and stepped up within five minutes. Others are answered forbidden or step_up_required, and every read is recorded.