Reports
SpeyBooks provides 7 financial reports, all computed from the double-entry ledger in real time. Reports have no stored state of their own - every figure is derived from posted transactions at query time using Decimal.js for arbitrary-precision arithmetic.
This guide explains when to use each report, how date ranges work, and how to combine them into a dashboard or reporting workflow. For the full endpoint reference, see Reports API.
How reports work
All reports are read-only GET endpoints. They accept date parameters (either a range or a point-in-time) and return computed figures. No transactions or balances are created or modified.
Reports follow standard accounting conventions: revenue is stored as credits in the ledger but displayed as positive values on reports. Expenses are stored as debits and displayed as positive values. Assets are debits; liabilities and equity are credits.
Date parameters
Reports use two styles of date parameter:
| Parameter style | Reports | Meaning |
|---|---|---|
from + to | Profit & Loss, VAT Return | Activity during a period (transactions within the range) |
asOf / asOfDate | Balance Sheet, Trial Balance, Aged Debtors, Aged Creditors | Cumulative position at a point in time (all transactions up to and including that date) |
The Dashboard uses neither - it defaults to the current open financial period, capped at today's date (year-to-date, not projected to period end). You can optionally pass a periodId to query a different period.
Profit & Loss
The income statement for a date range. Groups accounts by type (revenue, expense) and computes gross profit and net profit. Each account shows its code, name, and balance for the period.
Set comparative=true to include the equivalent prior period. The prior period is calculated as the same number of days ending the day before your from date. So querying 6 April 2025 to 19 February 2026 (320 days) produces a comparative period of 21 May 2024 to 5 April 2025 (also 320 days).
Balance Sheet
Statement of financial position as at a specific date. Returns assets, liabilities, equity, and retained earnings (computed as cumulative revenue minus expenses).
The balanced flag verifies the balance sheet equation: Assets = Liabilities + Equity + Retained Earnings. If balanced is false, there is a ledger inconsistency that needs investigation - in practice this should never happen because the PostgreSQL trigger rejects any transaction where debits do not equal credits.
Dashboard
An aggregated view designed for the home screen. Returns year-to-date P&L, bank balance, invoice statistics (outstanding and overdue counts with amounts), and recent transaction count.
Tax set-aside
The dashboard includes a taxSetAside object computed server-side from year-to-date figures:
Corporation Tax is calculated at 19% on profits up to GBP 250,000, and 25% above that threshold. The ctRate field shows which rate was applied.
VAT set-aside depends on the organisation's VAT scheme. For standard VAT, it is output VAT minus input VAT (clamped to zero or above). For flat rate scheme (FRS), it is gross turnover (calculated as revenue plus 20% VAT) multiplied by the flat rate percentage. For organisations not registered for VAT, it is zero.
Available is the bank balance minus total set-aside, clamped to zero or above. This represents the cash available after setting aside estimated tax obligations.
Aged Debtors and Aged Creditors
Outstanding receivables (debtors) and payables (creditors) grouped by contact and classified into aging buckets based on days past the due date:
| Bucket | Meaning |
|---|---|
current | Not yet due |
days1to30 | 1-30 days overdue |
days31to60 | 31-60 days overdue |
days61to90 | 61-90 days overdue |
days90plus | More than 90 days overdue |
Amounts are calculated as invoice total minus amount paid. Only invoices with a positive outstanding balance are included. Both reports default to today's date if asOfDate is not specified.
Aged Debtors covers sales invoices; Aged Creditors covers purchase invoices (bills). The response structure is identical for both, making it straightforward to render them with the same UI component.
VAT Return Summary
VAT data for a period, structured for HMRC Making Tax Digital reporting. Returns output VAT (charged on revenue), input VAT (reclaimed on expenses), and the net position.
The breakdown array provides per-rate detail, split by output and input type. Each entry shows the net amount and VAT amount for that rate, which is the data needed for a detailed VAT rate table.
The boxes object maps directly to HMRC's standard boxes 1-9. The vatLiabilityMovement field shows the movement on the VAT liability control account (2100) for the period. payable is true when net VAT is positive (owe HMRC); reclaimable is true when negative (refund due).
See the VAT Returns guide for the full filing workflow.
Trial Balance
Lists all accounts with non-zero balances as at a given date, split into debit and credit columns. Each account shows either a debit or credit value, never both.
The balanced flag verifies that total debits equal total credits. This is the fundamental double-entry check. If balanced is false, investigate immediately - the ledger has an inconsistency.
Accounts with zero balances are excluded from the response.
Financial periods
Periods define fiscal year boundaries (for example, 6 April to 5 April for UK tax years). Use GET /reports/periods to list all periods, and GET /reports/periods/{id} for detail on a specific period.
Periods can be open or closed. Closed periods include summary figures (total revenue, total expenses, net profit) computed at close time. The Dashboard defaults to the current open period.
Period IDs are plain integers, not prefixed.
Building a reporting workflow
A typical month-end review combines several reports:
- Dashboard - quick overview of year-to-date position, outstanding invoices, and tax set-aside
- Profit & Loss with
comparative=true- compare current period against the prior year - Trial Balance - verify the books balance before producing other reports
- Aged Debtors - identify overdue invoices that need chasing
- Balance Sheet - snapshot of the financial position for stakeholders
- VAT Return (quarterly) - compute the VAT liability for HMRC filing
All reports can be exported to CSV via the web interface. The API returns JSON, so integrations that need CSV can transform the response or use the CSV export endpoints directly.
Related endpoints
- Reports API - full endpoint reference
- VAT Returns Guide - VAT filing workflow
- Bank Reconciliation Guide - ensure transactions are posted before running reports