9-Box VAT Calculation — Xero
This page documents, step by step, exactly how Complyax turns a client’s Xero ledger into the nine HMRC VAT return boxes (the “9-box” return) during a VAT reconciliation. It is written so a qualified accountant can independently verify that both the data we ingest and the calculation procedure are correct.
For reviewers: every rule below reflects the live calculation engine (
calculateVatBoxes) and the Xero ingestion path (shadowVat.service.ts). The figure we produce is a shadow calculation — an independent recomputation of what the return should be — which is then compared box-by-box against the client’s actual HMRC MTD return.
Step 1 — Connect & identify the accounting basis
Xero is connected per client via OAuth (see Integrations → Xero & QuickBooks). Before any figures are pulled, Complyax reads the organisation’s VAT accounting basis directly from Xero:
- Source:
GET /api.xro/2.0/Organisation→Organisations[0].SalesTaxBasis SalesTaxBasis = "CASH"→ Cash accounting basis- Any other value → Accrual (invoice) basis
- If the value cannot be read, Complyax defaults to Accrual (the safer, more common basis).
The basis determines both the fetch window and how each transaction is dated:
| Basis | Fetch window | Transaction assigned to period by |
|---|---|---|
| Accrual | From the period start date | Document (transaction) date |
| Cash | Period start minus a 12-month lookback | Real payment/allocation date |
The 12-month lookback on cash basis ensures invoices raised in an earlier quarter but paid in the current VAT period are captured (from the invoice Payments array).
Step 2 — Which Xero records are ingested
Complyax queries the following Xero endpoints for the window (paginated at 100 records per page, with proactive rate-limiting):
| Xero endpoint | Type mapping | Notes |
|---|---|---|
| Invoices | ACCREC → SALES, otherwise PURCHASE | Uses the invoice Payments array for cash-basis dating |
| CreditNotes | ACCRECCREDIT → SALES, otherwise PURCHASE | Amounts negated (reduce the return); dated by issue, with Allocations for cash basis |
| BankTransactions | RECEIVE → SALES, otherwise PURCHASE (SPEND) | Settle at transaction date |
| Manual Journals | line-level, TaxType decides SALES vs PURCHASE | Included where they carry a VAT TaxType |
How each record becomes a transaction
For every document we derive a single header-level transaction (invoices/credit notes/bank transactions):
netAmount=SubTotalvatAmount=TotalTax- Credit notes are sign-flipped (negative net and VAT).
Step 3 — Resolving the tax code
Xero exposes a human-readable TaxType on each line. Complyax reads LineItems[0].TaxType (falling back to a generic INPUT/OUTPUT marker only when absent).
The tax code is then normalised through Firm Settings → Tax Code Mapping. Each firm can map a Xero TaxType to a Complyax system tag so bespoke codes classify correctly:
| System tag | Meaning |
|---|---|
PVA_PURCHASE | Import under Postponed VAT Accounting |
...C79... | Standard (non-postponed) import, reclaimed via C79 certificate |
CIS_REVERSE_SALE / CIS_REVERSE_PURCHASE / ...DRC... / ...REVERSE... | Domestic Reverse Charge |
...EC... / ...EU... | Intra-EU goods (relevant under the NI Protocol) |
FRS_CAPITAL_ASSET | Capital asset purchase under the Flat Rate Scheme |
OUTSIDE_SCOPE / NON_BUSINESS_EXEMPT | Excluded from the return |
If no firm mapping exists, the raw TaxType is classified by substring matching on the same keywords (e.g. a code containing PVA, EC/EU, CIS/DRC/REVERSE, C79, OUTPUT/SALE). Xero’s own tax types (e.g. OUTPUT2, INPUT2, ECZRINPUT, RRINPUT) are matched by these keywords — confirm bespoke ones are mapped.
Step 4 — Client VAT profile flags
Three client-profile attributes change the calculation:
| Flag | Derived from | Effect |
|---|---|---|
| Flat Rate Scheme (FRS) | Client type contains FRS (rate from FRS_<pct>, default 14.5%) | Uses the flat-rate method (Step 5b) |
| Northern Ireland | VRN starts with XI | Enables Box 2 / Box 8 / Box 9 EU-goods treatment |
| Partial exemption | Client flag + recovery rate % | Input VAT into Box 4 is scaled by the recovery rate |
Step 5a — Standard / cash method (the 9 boxes)
Each transaction is added to the boxes as follows.
Sales
| Classification | Box 1 (Output VAT) | Box 6 (Sales ex-VAT) | Box 8 |
|---|---|---|---|
| Standard sale | + VAT | + Net | — |
Domestic Reverse Charge sale (CIS_REVERSE_SALE) | — | + Net | — |
| EU-goods sale, GB | — | + Net | — |
| EU-goods sale, Northern Ireland | — | — | + Net |
OUTSIDE_SCOPE / NON_BUSINESS_EXEMPT | excluded entirely |
Purchases
| Classification | Box 1 | Box 2 | Box 4 (Input VAT) | Box 7 (Purchases ex-VAT) | Box 9 |
|---|---|---|---|---|---|
| Standard domestic purchase | — | — | + VAT¹ | + Net | — |
| Postponed VAT Accounting (PVA) | + VAT | — | + VAT¹ | + Net | — |
| Domestic Reverse Charge purchase (CIS/DRC) | + VAT | — | + VAT¹ | + Net | — |
| Import with C79 (GB) | — | — | + VAT¹ | + Net | — |
| EU-goods acquisition, Northern Ireland | — | + VAT | + VAT¹ | — | + Net |
¹ Partial exemption: where a client is partially exempt, the Box 4 input-VAT addition is multiplied by the recovery rate (e.g. 70% recovery → VAT × 0.70). This applies to all purchase categories above.
Derived boxes
- Box 3 (Total VAT due) = Box 1 + Box 2
- Box 5 (Net VAT) = | Box 3 − Box 4 |
Step 5b — Flat Rate Scheme method
If the client is on FRS, the standard method above is replaced:
- Flat-rate percentage comes from the client type tag
FRS_<pct>(default 14.5%). - Gross turnover = Σ (Net + VAT) of all sales, excluding
OUTSIDE_SCOPE/NON_BUSINESS_EXEMPT. - Box 1 = Gross turnover × flat-rate %
- Box 6 = Gross turnover × flat-rate %
- Box 4 — capital assets only: a
FRS_CAPITAL_ASSETpurchase with a gross value ≥ £2,000 adds its VAT to Box 4 (VAT Notice 733). The £2,000 test is per single purchase; ingestion maps one transaction per document (header level), so this matches the per-purchase rule. - Northern Ireland EU goods are accounted for outside the flat rate — EU sales → Box 8; EU acquisitions → Box 2, Box 4, Box 7 and Box 9.
- Box 3 = Box 1 + Box 2; Box 5 = |Box 3 − Box 4|.
FRS and partial exemption are mutually exclusive HMRC schemes, so the recovery-rate scaling is never applied on the FRS path.
Step 6 — Comparison against HMRC & anomaly detection
The nine calculated boxes are compared against the client’s actual HMRC MTD return for the period:
| Box | Calculated from | HMRC field |
|---|---|---|
| 1 | Output VAT | vatDueSales |
| 2 | EU acquisition VAT (NI) | vatDueAcquisitions |
| 3 | Box 1 + Box 2 | totalVatDue |
| 4 | Input VAT reclaimed | vatReclaimedCurrPeriod |
| 5 | Net VAT | netVatDue |
| 6 | Sales ex-VAT | totalValueSalesExVAT |
| 7 | Purchases ex-VAT | totalValuePurchasesExVAT |
| 8 | EU goods supplied (NI) | totalValueGoodsSuppliedExVAT |
| 9 | EU acquisitions (NI) | totalAcquisitionsExVAT |
For each box, variance = HMRC value − calculated value, risk-rated:
- £0 → LOW
- £0.01 – £10 → MEDIUM
- > £10 → HIGH
Alongside the box comparison, the Rules Engine raises transaction-level anomalies: missing evidence (VAT charged but no attached document), duplicates (same supplier + date + net amount), rate anomalies and period mismatches. These populate the Anomalies Console (see VAT Reconciliation).
Reviewer checklist
- Accounting basis in Xero (
Organisation.SalesTaxBasis) matches how the client actually files. - All bespoke Xero tax types have a Firm Settings → Tax Code Mapping entry.
- Import codes are tagged correctly as PVA vs C79 (they land in different boxes).
- Manual Journals carrying VAT are intended for the return (they are ingested at line level).
- Partial-exemption clients have a recovery rate set on the client profile.
- For NI clients, the VRN begins
XIso EU-goods boxes (2/8/9) engage.
See the equivalent 9-Box VAT Calculation — QuickBooks page for the QuickBooks ingestion path; the box mathematics (Steps 4–6) are identical.