9-Box VAT Calculation — QuickBooks

This page documents, step by step, exactly how Complyax turns a client’s QuickBooks Online 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 QuickBooks 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

QuickBooks is connected per client via OAuth (see Integrations → Xero & QuickBooks). Before any figures are pulled, Complyax reads the company’s VAT accounting basis directly from QuickBooks:

• Source: GET /v3/company/{realmId}/preferences → Preferences.TaxPrefs.TaxSystem
• TaxSystem = "CASH" → Cash accounting basis
• Any other value → Accrual (invoice) basis
• If the preference 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:

The 12-month lookback on cash basis ensures invoices raised in an earlier quarter but paid in the current VAT period are captured.

Step 2 — Which QuickBooks records are ingested

Complyax queries the following QuickBooks entities for the window (via the QBO Query API, paginated at 1,000 rows per response, throttled to ~450 requests/min):

Manual Journal Entries are deliberately NOT auto-included. Any QuickBooks Journal Entry carrying a VAT tax code inside the period is flagged in the run log for manual accountant review rather than being auto-classified — manual VAT journal adjustments require professional judgement, not automatic bucketing.

How each record becomes a transaction

For every document we derive a single header-level transaction (never per line item):

• vatAmount = TxnTaxDetail.TotalTax
• netAmount = TotalAmt − TotalTax
• Refunds / credits are sign-flipped (negative amounts).

Step 3 — Resolving the tax code

QuickBooks exposes only an opaque numeric TaxCodeRef on each transaction. Complyax:

1. Loads the company’s TaxCode reference table and maps each ref id → the human-readable TaxCode.Name (upper-cased).
2. Uses the header TxnTaxDetail.TxnTaxCodeRef first, falling back to the first line’s TaxCodeRef.
3. If resolution fails, falls back to a stable placeholder (QB_TAX_CODE_<id> or UNMAPPED_QB_TAX_CODE) — it never silently mislabels a transaction as a generic rate.

The resolved code is then normalised through Firm Settings → Tax Code Mapping. Each firm can map a QuickBooks tax-code name to a Complyax system tag so bespoke codes classify correctly:

If no firm mapping exists, the raw code name is classified by substring matching on the same keywords (e.g. a code containing PVA, EC/EU, CIS/DRC/REVERSE, C79, OUTPUT/SALE).

Step 4 — Client VAT profile flags

Three client-profile attributes change the calculation:

Step 5a — Standard / cash method (the 9 boxes)

Each transaction is added to the boxes as follows.

Sales

Purchases

¹ 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:

1. Flat-rate percentage comes from the client type tag FRS_<pct> (default 14.5%).
2. Gross turnover = Σ (Net + VAT) of all sales, excluding OUTSIDE_SCOPE / NON_BUSINESS_EXEMPT.
3. Box 1 = Gross turnover × flat-rate %
4. Box 6 = Gross turnover × flat-rate %
5. Box 4 — capital assets only: a FRS_CAPITAL_ASSET purchase 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.
6. 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.
7. 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:

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 QuickBooks (TaxPrefs.TaxSystem) matches how the client actually files.
• All bespoke QuickBooks tax codes have a Firm Settings → Tax Code Mapping entry.
• Import codes are tagged correctly as PVA vs C79 (they land in different boxes).
• Any VAT-bearing Journal Entries flagged in the run log have been reviewed manually.
• Partial-exemption clients have a recovery rate set on the client profile.
• For NI clients, the VRN begins XI so EU-goods boxes (2/8/9) engage.

See the equivalent 9-Box VAT Calculation — Xero page for the Xero ingestion path; the box mathematics (Steps 4–6) are identical.