energy.climate-change-levy

levy = quantity x main rate for the commodity on the date of supply

export function climateChangeLevy(commodity: CclCommodity, quantity: number, onDate: string, qualifyingUse: boolean, mode: RoundingMode): ClimateChangeLevy

export type CclCommodity = "electricity" | "gas" | "lpg" | "other";

/** The levy, the rate it was charged at, and whether the supply was outside it. */
export interface ClimateChangeLevy {
  readonly commodity: string;
  /** kWh or kg */
  readonly unit: string;
  /** main rate in thousandths of a penny per unit: £0.00775/kWh is 775 */
  readonly rate: number;
  /** true when qualifying use kept the supply out of the levy */
  readonly excluded: boolean;
  /** GBP, zero when excluded */
  readonly levy: Money;
  /** when the rate came into force */
  readonly validFrom: string;
  /** when it stops; null while it is the latest rate published */
  readonly validTo: string | null;
}

import { climateChangeLevy } from "#fune/energy.climate-change-levy@^1";

import { type RoundingMode, roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { CCL_RATES, CCL_RATES_HISTORY } from "./energy_climate_change_levy_data.ts";  ← this capability’s own data, compiled from data/ccl-rates.json into the same file by fune build
import { type ClimateChangeLevy, type CclCommodity } from "./energy_climate_change_levy_types.ts";

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
// quantity (thousandths of a unit) x rate (thousandths of a penny) is in
// millionths of a penny.
const DIVISOR = 1_000_000;

/**
 * The Climate Change Levy on one supply, at the main rate in force on
 * `onDate`. A qualifying-use supply (domestic, charity non-business or
 * de minimis) is outside the levy and comes back excluded, with a zero levy.
 */
export function climateChangeLevy(
  commodity: CclCommodity,
  quantity: number,
  onDate: string,
  qualifyingUse: boolean,
  mode: RoundingMode
): ClimateChangeLevy {
  if (!ISO_DATE.test(onDate)) {
    throw new RangeError(`onDate must be an ISO date (YYYY-MM-DD), received "${onDate}"`);
  }
  if (!Number.isInteger(quantity) || quantity < 0) {
    throw new RangeError(`quantity must be a whole number of thousandths of a unit, 0 or more, received ${quantity}`);
  }
  if (!CCL_RATES.some((r) => r.commodity === commodity)) {
    throw new RangeError(`unknown commodity "${commodity}": expected electricity, gas, lpg or other`);
  }
  let best: (typeof CCL_RATES)[number] | null = null;
  for (const r of CCL_RATES) {
    if (r.commodity !== commodity || onDate < r.validFrom) continue;
    if (r.validTo !== null && onDate > r.validTo) continue;
    if (best === null || r.validFrom > best.validFrom) best = r;
  }
  if (best === null) {
    // A pruned build must not answer an old date with a newer rate.
    if (CCL_RATES_HISTORY !== "full") {
      let earliest: string | null = null;
      for (const r of CCL_RATES) {
        if (r.commodity === commodity && (earliest === null || r.validFrom < earliest)) earliest = r.validFrom;
      }
      if (earliest !== null && onDate < earliest) {
        throw new RangeError(
          `no Climate Change Levy rate for ${commodity} on ${onDate}: this build was installed with history=${CCL_RATES_HISTORY}, ` +
            `so it only carries rates from ${earliest}. Reinstall with history=full for older supplies.`
        );
      }
    }
    throw new RangeError(`no Climate Change Levy rate for ${commodity} on ${onDate}`);
  }
  let pence = 0;
  if (!qualifyingUse) {
    const product = quantity * best.rate;
    if (product > Number.MAX_SAFE_INTEGER) {
      throw new RangeError("levy too large to calculate exactly");
    }
    pence = roundDiv(product, DIVISOR, mode);
  }
  return {
    commodity,
    unit: best.unit,
    rate: best.rate,
    excluded: qualifyingUse,
    levy: money(pence, "GBP"),
    validFrom: best.validFrom,
    validTo: best.validTo,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 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 energy.climate-change-levy

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./energy.climate-change-levy-1.0.2-typescript.fune, or fetch it from a terminal with fune pull energy.climate-change-levy@1.0.2:typescript.

The whole function, every language, is one file too: energy.climate-change-levy-1.0.2.fune, 28,839 bytes, sha256 18139232039628d0676a0d19756af8beb5c03b60f1811a68eccf403a14f406fc. It installs into a project of any language.

// fune: before energy.climate-change-levy

// fune: after energy.climate-change-levy

// fune: replace math.round-div in energy.climate-change-levy
// fune: replace money.amount in energy.climate-change-levy

// fune: step energy.climate-change-levy after <n|label>

More from the author

Electricity and gas are charged per kWh; LPG and "any other taxable commodity" (coal, coke, petroleum coke) per kg. The rates are dated data from HMRC, from 1 April 2023 to the rates already announced for 1 April 2027.

## Qualifying use: the domestic and de minimis exclusion

CCL does not apply to supplies for **domestic use** or **charity non-business use**, and supplies small enough to be **de minimis** are excluded too. Those are the same supplies that get VAT at the reduced 5% rate as "qualifying use" (VAT Notice 701/19): for a business, up to an average of 33 kWh a day (1,000 kWh a month) of electricity, or 145 kWh a day (4,397 kWh a month) of piped gas. Pass `qualifyingUse: true` for any of these and the result has `excluded: true` and a zero levy; the rate is still returned, so a bill can show which rate it did not charge. Deciding whether a supply qualifies (including the 60% mixed-use rule) is the caller's, because it depends on the customer, not the kWh alone.

## Units and rounding

- Quantities are integers in **thousandths** of the unit (watt-hours or grams), so part-units are exact. - Rates are integers in **thousandths of a penny** per unit, exactly the five decimal places of pounds HMRC publishes (£0.00775 per kWh is `775`). - The levy is rounded once to a whole penny by `mode` (suppliers usually round half-up per bill). Quantity times rate must stay within 2^53.

## Not covered

- **Reduced rates for climate change agreement holders** (a percentage discount off the main rate: 92% for electricity, 89% for gas from April 2024) — apply the discount to the result if the site holds a CCA. - **Carbon Price Support rates** paid by generators. - Supplies spanning a rate change on 1 April: split the quantity by date and call once per part.

## Dates and pruning

Each rate applies from `validFrom` to `validTo` inclusive; the latest has a null `validTo`. A build installed with `history=current` keeps only rates still in force, and a date before the earliest surviving rate is refused with an explanation rather than charged at a newer rate.

## Sources

- HMRC, "Climate Change Levy rates", https://www.gov.uk/guidance/climate-change-levy-rates (main rates from 1 April 2023, 2024, 2025, 2026 and 2027; last updated 27 November 2025). - HMRC, "VAT on fuel and power (VAT Notice 701/19)", https://www.gov.uk/guidance/vat-on-fuel-and-power-notice-70119 (paragraph 2.8: the levy does not apply to domestic or charity non-business use, and de minimis supplies are excluded; paragraphs 4.2 and 5.2: the de minimis limits).

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