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.

MTD direct submission Direct submission to HMRC from within SpeyBooks is on the roadmap. Currently, SpeyBooks generates the VAT report data which you can use with your preferred filing method. The nine-box figures are calculated to HMRC's specification and ready for submission.

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