construction.cis-deduction

def cis_deduction(payment: Money, materials: Money, status: CisStatus, on_date: str, mode: RoundingMode) -> CisDeduction

CisStatus = Literal["gross", "standard", "higher"]

@dataclass(frozen=True)
class CisDeduction:
    """The payment split into what the deduction is taken from and what is paid."""

    #: the payment excluding VAT, as passed
    payment: Money
    #: the part the deduction does not apply to
    materials: Money
    #: payment less materials: what the rate is applied to
    labour: Money
    #: the rate applied, 2000 = 20%
    basis_points: int
    #: withheld and paid to HMRC
    deduction: Money
    #: payment less deduction, before any VAT is added
    net_payment: Money

from fune.construction.cis_deduction import cis_deduction  # construction.cis-deduction@^1

import re

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

ISO_DATE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")


def _rate_on(status: str, on_date: str) -> int:
    best = None
    earliest = None
    for rule in CIS_RATES:
        if rule.status != status:
            continue
        if earliest is None or rule.valid_from < earliest:
            earliest = rule.valid_from
        if on_date < rule.valid_from:
            continue
        if rule.valid_to is not None and on_date > rule.valid_to:
            continue
        if best is None or rule.valid_from > best.valid_from:
            best = rule
    if best is not None:
        return best.basis_points
    # 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" and earliest is not None and on_date < earliest:
        raise ValueError(
            "no CIS rate for %s on %s: this build was installed with history=%s, "
            "so it only carries rates from %s. Reinstall with history=full for older payments."
            % (status, on_date, CIS_RATES_HISTORY, earliest)
        )
    raise ValueError("no CIS rate for %s on %s" % (status, on_date))


def cis_deduction(payment: Money, materials: Money, status: CisStatus, on_date: str, mode: RoundingMode) -> CisDeduction:
    """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.
    """
    if status not in ("gross", "standard", "higher"):
        raise ValueError('unknown CIS status "%s"' % (status,))
    if not isinstance(on_date, str) or not ISO_DATE.fullmatch(on_date):
        raise ValueError('onDate must be an ISO date (YYYY-MM-DD), received "%s"' % (on_date,))
    if payment.minor < 0:
        raise ValueError("payment must not be negative, received %d" % (payment.minor,))
    if materials.minor < 0:
        raise ValueError("materials must not be negative, received %d" % (materials.minor,))
    labour = subtract_money(payment, materials)
    if labour.minor < 0:
        raise ValueError("materials (%d) cannot exceed the payment (%d)" % (materials.minor, payment.minor))
    basis_points = _rate_on(status, on_date)
    deduction = apply_rate(labour, basis_points, mode)
    return CisDeduction(
        payment=payment,
        materials=materials,
        labour=labour,
        basis_points=basis_points,
        deduction=deduction,
        net_payment=subtract_money(payment, deduction),
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 4 dependencies, pins them in fune.lock, downloads only the Python 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 Python implementation. Install it without the registry with fune add ./construction.cis-deduction-1.0.2-python.fune, or fetch it from a terminal with fune pull construction.cis-deduction@1.0.2:python.

The whole function, every language, is one file too: construction.cis-deduction-1.0.2.fune, 33,328 bytes, sha256 05e4a04b1844ab419c0e958d1e26ba9a3d67b236a001886fd0e72033e38a7696. 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

1.0.1 fixes Python accepting a trailing newline or non-ASCII digits in onDate; adds tests.

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

1.0.2 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files