finance.tax.vat-return Unreviewed

export function vatReturn(transactions: readonly VatTransaction[], periodStart: string, periodEnd: string): VatReturn

export type VatDirection = "sale" | "purchase";

export type VatTreatment = "taxable" | "exempt" | "outside-scope" | "domestic-reverse-charge" | "services-reverse-charge" | "postponed-import-vat" | "ni-eu-goods";

/** One sale or purchase, as the ledger categorised it. */
export interface VatTransaction {
  /** tax point */
  readonly date: string;
  readonly direction: VatDirection;
  readonly treatment: VatTreatment;
  /** excluding VAT, GBP; negative for a credit note */
  readonly net: Money;
  /** the VAT on it (for reverse charges, the VAT self-accounted); negative for a credit note */
  readonly vat: Money;
}

/** The nine boxes. Boxes 1 to 5 in pounds and pence; boxes 6 to 9 in whole pounds. */
export interface VatReturn {
  /** VAT due on sales and other outputs */
  readonly box1: Money;
  /** VAT due on acquisitions of goods into Northern Ireland from the EU */
  readonly box2: Money;
  /** total VAT due: box 1 plus box 2 */
  readonly box3: Money;
  /** VAT reclaimed on purchases and other inputs */
  readonly box4: Money;
  /** net VAT: the difference between boxes 3 and 4, never negative */
  readonly box5: Money;
  /** total value of sales and other outputs excluding VAT, pence dropped */
  readonly box6: Money;
  /** total value of purchases and other inputs excluding VAT, pence dropped */
  readonly box7: Money;
  /** goods supplied from Northern Ireland to the EU, pence dropped */
  readonly box8: Money;
  /** goods acquired into Northern Ireland from the EU, pence dropped */
  readonly box9: Money;
  /** true when box 4 exceeds box 3, so HMRC owes the business */
  readonly repayment: boolean;
  /** how many transactions fell in the period */
  readonly transactions: number;
}

import { vatReturn } from "#fune/finance.tax.vat-return@^1";

import { daysBetween } from "./dates_days_between.ts";  ← from dates.days-between ^1.0.0 · built alongside by fune
import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { addMoney } from "./money_add.ts";  ← from money.add ^1.0.0 · built alongside by fune
import { type Money, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type VatReturn, type VatTransaction } from "./finance_tax_vat_return_types.ts";

const ZERO_VAT_SALES = ["exempt", "outside-scope", "domestic-reverse-charge", "services-reverse-charge", "ni-eu-goods"];
const ZERO_VAT_PURCHASES = ["exempt", "outside-scope"];
const TREATMENTS = [
  "taxable",
  "exempt",
  "outside-scope",
  "domestic-reverse-charge",
  "services-reverse-charge",
  "postponed-import-vat",
  "ni-eu-goods",
];

/** Drop the pence, towards zero: boxes 6 to 9 are whole pounds. */
function wholePounds(amount: Money): Money {
  return money(roundDiv(amount.minor, 100, "down") * 100, amount.currency);
}

/**
 * The nine boxes of a UK VAT return for a period.
 *
 * Each transaction feeds the boxes its direction and treatment call for
 * (VAT Notice 700/12 sections 3 and 4.6); boxes 6 to 9 drop the pence after
 * totalling.
 */
export function vatReturn(transactions: readonly VatTransaction[], periodStart: string, periodEnd: string): VatReturn {
  if (daysBetween(periodStart, periodEnd) < 0) {
    throw new RangeError(`VAT return period ends ${periodEnd}, before it starts ${periodStart}`);
  }
  const box = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0].map(() => money(0, "GBP"));
  let count = 0;
  transactions.forEach((t, index) => {
    const n = index + 1;
    if (t.direction !== "sale" && t.direction !== "purchase") {
      throw new RangeError(`transaction ${n}: unknown direction "${t.direction}"`);
    }
    if (!TREATMENTS.includes(t.treatment)) {
      throw new RangeError(`transaction ${n}: unknown VAT treatment "${t.treatment}"`);
    }
    if (t.net.currency !== "GBP" || t.vat.currency !== "GBP") {
      throw new RangeError(`transaction ${n}: amounts must be in GBP`);
    }
    const sale = t.direction === "sale";
    if (sale && t.treatment === "postponed-import-vat") {
      throw new RangeError(`transaction ${n}: postponed-import-vat applies to purchases only`);
    }
    if (t.vat.minor !== 0 && (sale ? ZERO_VAT_SALES : ZERO_VAT_PURCHASES).includes(t.treatment)) {
      throw new RangeError(`transaction ${n}: ${t.treatment} ${t.direction}s must have zero VAT`);
    }
    const inPeriod = daysBetween(periodStart, t.date) >= 0 && daysBetween(t.date, periodEnd) >= 0;
    if (!inPeriod) return;
    count += 1;

    const add = (b: number, amount: Money): void => {
      box[b] = addMoney(box[b], amount);
    };
    if (sale) {
      if (t.treatment === "taxable") add(1, t.vat);
      if (t.treatment !== "outside-scope") add(6, t.net);
      if (t.treatment === "ni-eu-goods") add(8, t.net);
    } else {
      switch (t.treatment) {
        case "taxable":
          add(4, t.vat);
          add(7, t.net);
          break;
        case "exempt":
          add(7, t.net);
          break;
        case "outside-scope":
          break;
        case "services-reverse-charge":
          add(6, t.net);
        // falls through: the customer also accounts as for a domestic reverse charge
        case "domestic-reverse-charge":
        case "postponed-import-vat":
          add(1, t.vat);
          add(4, t.vat);
          add(7, t.net);
          break;
        case "ni-eu-goods":
          add(2, t.vat);
          add(4, t.vat);
          add(7, t.net);
          add(9, t.net);
          break;
      }
    }
  });

  const box3 = addMoney(box[1], box[2]);
  const difference = box3.minor - box[4].minor;
  return {
    box1: box[1],
    box2: box[2],
    box3,
    box4: box[4],
    box5: money(difference < 0 ? -difference : difference, "GBP"),
    box6: wholePounds(box[6]),
    box7: wholePounds(box[7]),
    box8: wholePounds(box[8]),
    box9: wholePounds(box[9]),
    repayment: difference < 0,
    transactions: count,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 4 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add finance.tax.vat-return

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./finance.tax.vat-return-1.0.1-typescript.fune, or fetch it from a terminal with fune pull finance.tax.vat-return@1.0.1:typescript.

The whole function, every language, is one file too: finance.tax.vat-return-1.0.1.fune, 37,576 bytes, sha256 81f3e3501c2945d9de2e7f02bbad017010b8b7bccd8e0ef52a5423d4419a8dcd. It installs into a project of any language.

// fune: before finance.tax.vat-return

// fune: after finance.tax.vat-return

// fune: replace dates.days-between in finance.tax.vat-return
// fune: replace math.round-div in finance.tax.vat-return
// fune: replace money.add in finance.tax.vat-return
// fune: replace money.amount in finance.tax.vat-return

// fune: step finance.tax.vat-return after <n|label>

More from the author

A transaction is in the period when its tax point (`date`) is on or after `periodStart` and on or before `periodEnd`; the rest are left out, so a whole ledger can be passed. Every transaction is still checked, in or out of the period, and errors name it by its 1-based position.

| treatment | sale | purchase | |---|---|---| | `taxable` (standard, reduced or zero-rated) | box 1 VAT, box 6 net | box 4 VAT, box 7 net | | `exempt` | box 6 net | box 7 net | | `outside-scope` (not a supply: wages, grants, loans, dividends) | nothing | nothing | | `domestic-reverse-charge` (construction, specified goods) | box 6 net | box 1 and box 4 VAT, box 7 net | | `services-reverse-charge` (international services) | box 6 net | box 1 and box 4 VAT, boxes 6 and 7 net | | `postponed-import-vat` | refused | box 1 and box 4 VAT, box 7 net | | `ni-eu-goods` (Northern Ireland and the EU) | boxes 6 and 8 net | box 2 and box 4 VAT, boxes 7 and 9 net |

The mapping follows HMRC VAT Notice 700/12, "How to fill in and submit your VAT Return", sections 3.2 to 3.10 (the boxes) and 4.6 (reverse charge: the supplier fills in box 6; the customer boxes 1, 4 and 7, plus box 6 for gold and international services), https://www.gov.uk/guidance/how-to-fill-in-and-submit-your-vat-return-vat-notice-70012, read on 23 September 2026. Exempt, outside-scope, supplier-side reverse charge and NI-to-EU sales must carry zero VAT, and a VAT figure on them is refused as a miscategorisation.

**Credit notes** are negative transactions and reduce the boxes they would have fed, as 3.2 and 3.5 require ("deduct any VAT on credit notes").

**Box 5** is the difference between boxes 3 and 4 without a sign, as the form requires ("do not enter a minus sign in box 5"); `repayment` says which way it goes.

**Boxes 6 to 9** are whole pounds. The pence are dropped after totalling (not per transaction), truncating towards zero, so 999.99 of sales is 999 in box 6. Notice 700/12 does not state the rounding for these boxes; dropping the pence is the common practice and should be confirmed.

**Not covered.** Input VAT is taken as fully recoverable: partial exemption, blocked input tax (business entertainment, most cars) and non-reclaimable import VAT must be taken out of the purchase's `vat` before it is passed. Special schemes (Flat Rate, see finance.tax.vat-flat-rate; cash accounting; retail and margin schemes) change several boxes and are not applied here, nor are bad debt relief, fuel scale charges or error corrections, other than by the caller entering them as taxable sales or purchases. Amounts must be in GBP.

## Before you rely on this

**Not professional advice.** This capability calculates tax figures from published rules. It is a software component for developers, not tax advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a chartered accountant or VAT specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified chartered accountant or VAT specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files