construction.cis-deduction

export function cisDeduction(payment: Money, materials: Money, status: CisStatus, onDate: string, mode: RoundingMode): CisDeduction

export type CisStatus = "gross" | "standard" | "higher";

/** The payment split into what the deduction is taken from and what is paid. */
export interface CisDeduction {
  /** the payment excluding VAT, as passed */
  readonly payment: Money;
  /** the part the deduction does not apply to */
  readonly materials: Money;
  /** payment less materials: what the rate is applied to */
  readonly labour: Money;
  /** the rate applied, 2000 = 20% */
  readonly basisPoints: number;
  /** withheld and paid to HMRC */
  readonly deduction: Money;
  /** payment less deduction, before any VAT is added */
  readonly netPayment: Money;
}

import { cisDeduction } from "#fune/construction.cis-deduction@^1";

import { type RoundingMode } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { subtractMoney } from "./money_add.ts";  ← from money.add ^1.0.0 · built alongside by fune
import { type Money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { applyRate } from "./money_apply_rate.ts";  ← from money.apply-rate ^1.0.0 · built alongside by fune
import { CIS_RATES, CIS_RATES_HISTORY } from "./construction_cis_deduction_data.ts";  ← this capability’s own data, compiled from data/cis-rates.json into the same file by fune build
import { type CisDeduction, type CisStatus } from "./construction_cis_deduction_types.ts";

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;

function rateOn(status: string, onDate: string): number {
  let best: { basisPoints: number; validFrom: string } | null = null;
  let earliest: string | null = null;
  for (const rule of CIS_RATES) {
    if (rule.status !== status) continue;
    if (earliest === null || rule.validFrom < earliest) earliest = rule.validFrom;
    if (onDate < rule.validFrom) continue;
    if (rule.validTo !== null && onDate > rule.validTo) continue;
    if (best === null || rule.validFrom > best.validFrom) best = rule;
  }
  if (best !== null) return best.basisPoints;
  // A history=current build has dropped the old rows; say so rather than
  // answering an old payment at today's rate.
  if (CIS_RATES_HISTORY !== "full" && earliest !== null && onDate < earliest) {
    throw new RangeError(
      `no CIS rate for ${status} on ${onDate}: this build was installed with history=${CIS_RATES_HISTORY}, ` +
        `so it only carries rates from ${earliest}. Reinstall with history=full for older payments.`
    );
  }
  throw new RangeError(`no CIS rate for ${status} on ${onDate}`);
}

/**
 * The CIS deduction a contractor withholds from a subcontractor's payment.
 *
 * The rate applies only to the labour: VAT is left out by taking the payment
 * net of VAT, and materials (with consumables, non-travel fuel, plant hire and
 * prefabricated materials) are taken off before the rate is applied. Applying
 * 20% to the whole invoice is the classic over-deduction.
 */
export function cisDeduction(payment: Money, materials: Money, status: CisStatus, onDate: string, mode: RoundingMode): CisDeduction {
  if (status !== "gross" && status !== "standard" && status !== "higher") {
    throw new RangeError(`unknown CIS status "${status}"`);
  }
  if (!ISO_DATE.test(onDate)) {
    throw new RangeError(`onDate must be an ISO date (YYYY-MM-DD), received "${onDate}"`);
  }
  if (payment.minor < 0) {
    throw new RangeError(`payment must not be negative, received ${payment.minor}`);
  }
  if (materials.minor < 0) {
    throw new RangeError(`materials must not be negative, received ${materials.minor}`);
  }
  const labour = subtractMoney(payment, materials);
  if (labour.minor < 0) {
    throw new RangeError(`materials (${materials.minor}) cannot exceed the payment (${payment.minor})`);
  }
  const basisPoints = rateOn(status, onDate);
  const deduction = applyRate(labour, basisPoints, mode);
  return {
    payment,
    materials,
    labour,
    basisPoints,
    deduction,
    netPayment: subtractMoney(payment, deduction),
  };
}

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 construction.cis-deduction

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./construction.cis-deduction-1.0.0-typescript.fune, or fetch it from a terminal with fune pull construction.cis-deduction@1.0.0:typescript.

The whole function, every language, is one file too: construction.cis-deduction-1.0.0.fune, 32,006 bytes, sha256 dd6fa7c2bb71beabab099d76fc5b21a9dcc123675e9ee6d1d06b66e2676003c0. It installs into a project of any language.

// fune: before construction.cis-deduction

// fune: after construction.cis-deduction

// fune: replace math.round-div in construction.cis-deduction
// fune: replace money.add in construction.cis-deduction
// fune: replace money.amount in construction.cis-deduction
// fune: replace money.apply-rate in construction.cis-deduction

// fune: step construction.cis-deduction after <n|label>

More from the author

Only the labour. HMRC's steps are: start from the invoice, take off VAT, take off what the subcontractor paid for materials, consumable stores, fuel (except for travelling), plant hired for the job and manufacturing or prefabricating materials, and apply the rate to what is left. So `payment` is the payment **excluding VAT**, `materials` is all of those costs together (excluding VAT where the subcontractor is VAT registered), and the rate is applied to `payment - materials`. Applying 20% to the whole invoice is the usual mistake: 1,500.00 with 900.00 of materials withholds 120.00, not 300.00.

VAT is paid on top of `netPayment` in full (or reverse charged, see `construction.vat-reverse-charge`); CIS never touches it.

## Rates

Dated rows in `data/cis-rates.json`, looked up on the payment date:

| status | from | rate | |----------|------------|------| | gross | 2007-04-06 | 0% | | standard | 2007-04-06 | 20% (registered and matched) | | higher | 2007-04-06 | 30% (not registered, or not matched on verification) | | standard | 2000-04-06 to 2007-04-05 | 18% (CIS4 card holders) | | gross | 2000-04-06 to 2007-04-05 | 0% (CIS5/CIS6 certificate holders) |

There was no 30% rate before the 2007 scheme, so `higher` before 6 April 2007 is an error, as is any date before 6 April 2000 (earlier rates, 25% to 23%, are not carried). The table declares its effective columns, so a `history=current` build refuses dates before its horizon instead of answering them at today's rate.

## Rounding

HMRC does not publish a rounding rule for the deduction (the monthly return takes it in pounds and pence), so the rounding mode is an argument. `down` never withholds more than the rate; `half-up` is the ordinary commercial choice. Whichever you use, use the same one every month.

## Edges

Materials equal to the payment leave no labour and no deduction. Materials above the payment, negative amounts and mixed currencies are errors.

## Sources

- HMRC, "What you must do as a Construction Industry Scheme (CIS) contractor: Make deductions and pay subcontractors" (rates 20%, 30%, 0% and the items taken off before the rate): https://www.gov.uk/what-you-must-do-as-a-cis-contractor/make-deductions-and-pay-subcontractors - HMRC, "Construction Industry Scheme: a guide for contractors and subcontractors (CIS 340)": https://www.gov.uk/government/publications/construction-industry-scheme-cis-340 - HMRC internal manual CISR71020, "Deductions: overview: the rate of deduction under the Construction Industry Scheme" (the rate history): https://www.gov.uk/hmrc-internal-manuals/construction-industry-scheme-reform/cisr71020

Files