VAT Returns
Generate MTD-ready VAT return data derived entirely from the SpeyBooks ledger.
VAT returns are computed views over posted transactions. SpeyBooks does not store or edit VAT figures manually - the nine-box return is calculated from the ledger every time you request it.
MTD compatibility
From April 2022, all VAT-registered UK businesses must submit VAT returns using MTD-compatible software.
SpeyBooks generates MTD-compliant VAT return data in the standard nine-box format. The figures can be used for submission through your existing MTD filing process.
Prerequisites
Before generating a VAT return, you need:
- A VAT-registered organisation in SpeyBooks
- Complete and accurate ledger data for the reporting period
- All bank transactions for the period imported and categorised
VAT returns are calculated from posted transactions only. Draft or unposted transactions are excluded.
Generate a VAT report
Request the nine-box VAT return for a date range:
curl "https://api.speybooks.com/v1/reports/vat?from=2026-01-01&to=2026-03-31" \
-H "Authorization: Bearer sk_live_..."
The report is recomputed from the ledger on every request. Running it multiple times for the same period always produces the same result (assuming no new transactions have been posted).
Notes
- All monetary values are in minor units (pence)
status: "draft"indicates the figures have not been finalised- The report covers all posted transactions within the specified date range
VAT box meanings
| Box | Description | Example |
|---|---|---|
| 1 | VAT due on sales | 100000 |
| 2 | VAT due on EU acquisitions | 0 |
| 3 | Total VAT due (Box 1 + Box 2) | 100000 |
| 4 | VAT reclaimed on purchases | 25000 |
| 5 | Net VAT to pay or reclaim (Box 3 - Box 4) | 75000 |
| 6 | Total sales (excl. VAT) | 500000 |
| 7 | Total purchases (excl. VAT) | 125000 |
| 8 | Total EU supplies | 0 |
| 9 | Total EU acquisitions | 0 |
All values are in minor units. Box 5 value of 75000 = GBP 750.00 net VAT to pay.
How VAT is captured
SpeyBooks captures VAT at the point of transaction, not at submission time.
When you create an invoice with "vatRate": "standard", SpeyBooks automatically splits the amount into net and VAT components and posts them to the correct accounts. When you categorise a bank transaction as an expense with a VAT rate, the same split happens.
The VAT return report simply aggregates these already-posted amounts across the period.
VAT on sales (Box 1)
Sum of all VAT amounts on posted sales invoices and revenue transactions within the period. This comes from the VAT Output account (2200).
VAT on purchases (Box 4)
Sum of all VAT amounts on posted bills, expenses, and purchase transactions within the period. This comes from the VAT Input account (2201).
Net position (Box 5)
Box 3 minus Box 4. A positive number means you owe HMRC. A negative number means HMRC owes you a refund.
Deadlines
VAT returns are due:
| Frequency | Deadline |
|---|---|
| Quarterly | 1 month and 7 days after period end |
| Monthly | 1 month and 7 days after period end |
SpeyBooks does not currently track or surface VAT deadlines automatically.
Flat Rate Scheme
If your organisation uses the VAT Flat Rate Scheme, the VAT return calculation applies the flat rate percentage to gross turnover rather than computing input/output VAT separately. Set your VAT scheme in Settings > Organisation or via the Organisation API.
VAT computation invariants
SpeyBooks enforces the following:
- VAT reports are derived solely from posted transactions
- No VAT figures are manually editable
- Running the report for the same period and ledger state always produces identical figures
- VAT rates are applied at transaction time and stored, never retrospectively recalculated
Error codes
| Code | HTTP | Description |
|---|---|---|
validation_error | 400 | Missing or invalid date range |
unprocessable_entity | 422 | Ledger data incomplete for period |
Amount format
All monetary values are in minor units (pence for GBP):
100000 = GBP 1,000.00
75000 = GBP 750.00
Divide by 100 for display.
Related endpoints
- VAT Return Summary - endpoint reference
- Profit & Loss - revenue and expense breakdown
- Trial Balance - full account balances
- VAT Handling - how VAT rates are applied