retail.oss-vat

export function ossVat(net: Money, sellerCountry: string, customerCountry: string, euSalesPreviousYear: Money, euSalesThisYear: Money, optedIn: boolean, onDate: string): OssVat

/** Where VAT is due, at what rate, and how much. */
export interface OssVat {
  /** the member state whose VAT applies */
  readonly taxCountry: string;
  /** domestic (same country), origin (below the threshold: the seller's own VAT) or oss (the customer's VAT, declared through the One Stop Shop) */
  readonly scheme: string;
  /** that state's standard rate */
  readonly basisPoints: number;
  /** the EUR 10,000 threshold is exceeded this year or was last year */
  readonly thresholdExceeded: boolean;
  readonly net: Money;
  /** net at the rate, rounded half up */
  readonly vat: Money;
  readonly gross: Money;
}

import { ossVat } from "#fune/retail.oss-vat@^1";

import { type Money, 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 { OSS_RULES, OSS_RULES_HISTORY } from "./retail_oss_vat_data.ts";  ← this capability’s own data, compiled from data/oss-rules.json into the same file by fune build
import { type OssVat } from "./retail_oss_vat_types.ts";

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
const COUNTRY = /^[A-Z]{2}$/;

// The EU writes Greece as EL in VAT matters; ISO 3166 says GR. Accept both.
function country(code: string, name: string): string {
  if (!COUNTRY.test(code)) throw new RangeError(`${name} must be an ISO 3166-1 alpha-2 code, received "${code}"`);
  return code === "EL" ? "GR" : code;
}

function isMember(code: string): boolean {
  return OSS_RULES.some((r) => r.rule === "standard-rate" && r.country === code);
}

function lookup(rule: string, where: string, onDate: string): number {
  let best: { validFrom: string; value: number } | null = null;
  for (const r of OSS_RULES) {
    if (r.rule !== rule || r.country !== where) continue;
    if (onDate < r.validFrom || (r.validTo !== null && onDate > r.validTo)) continue;
    if (best === null || r.validFrom > best.validFrom) best = { validFrom: r.validFrom, value: r.value };
  }
  if (best !== null) return best.value;
  // A history=current build carries only the rules still in force; answering
  // an older date with today's rate is the failure the dates exist to prevent.
  if (OSS_RULES_HISTORY !== "full") {
    let earliest: string | null = null;
    for (const r of OSS_RULES) {
      if (r.rule === rule && r.country === where && (earliest === null || r.validFrom < earliest)) earliest = r.validFrom;
    }
    if (earliest !== null && onDate < earliest) {
      throw new RangeError(
        `no OSS rule "${rule}" for ${where} on ${onDate}: this build was installed with history=${OSS_RULES_HISTORY}, ` +
          `so it only carries rules from ${earliest}. Reinstall with history=full for older supplies.`,
      );
    }
  }
  throw new RangeError(`no OSS rule "${rule}" for ${where} on ${onDate}`);
}

/**
 * VAT on a business-to-consumer sale to another EU member state: the seller's
 * own rate while its cross-border sales stay within EUR 10,000 (and it has not
 * opted in), the customer's state's rate through the One Stop Shop once they
 * exceed it, and always the customer's for sellers outside the EU.
 */
export function ossVat(
  net: Money,
  sellerCountry: string,
  customerCountry: string,
  euSalesPreviousYear: Money,
  euSalesThisYear: Money,
  optedIn: boolean,
  onDate: string,
): OssVat {
  if (!ISO_DATE.test(onDate)) throw new RangeError(`onDate must be an ISO date (YYYY-MM-DD), received "${onDate}"`);
  const seller = country(sellerCountry, "sellerCountry");
  const customer = country(customerCountry, "customerCountry");
  if (!isMember(customer)) throw new RangeError(`customer country "${customerCountry}" is not an EU member state`);
  for (const [name, amount] of [
    ["euSalesPreviousYear", euSalesPreviousYear],
    ["euSalesThisYear", euSalesThisYear],
  ] as const) {
    if (amount.currency !== "EUR") throw new RangeError(`${name} must be in EUR, received ${amount.currency}`);
    if (amount.minor < 0) throw new RangeError(`${name} must not be negative, received ${amount.minor}`);
  }

  const threshold = lookup("distance-selling-threshold", "EU", onDate);
  const thresholdExceeded = euSalesPreviousYear.minor > threshold || euSalesThisYear.minor > threshold;

  let scheme: string;
  let taxCountry: string;
  if (seller === customer) {
    scheme = "domestic";
    taxCountry = customer;
  } else if (isMember(seller) && !thresholdExceeded && !optedIn) {
    scheme = "origin";
    taxCountry = seller;
  } else {
    scheme = "oss";
    taxCountry = customer;
  }

  const basisPoints = lookup("standard-rate", taxCountry, onDate);
  const vat = applyRate(net, basisPoints, "half-up");
  return {
    taxCountry,
    scheme,
    basisPoints,
    thresholdExceeded,
    net,
    vat,
    gross: money(net.minor + vat.minor, net.currency),
  };
}

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 retail.oss-vat

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

The whole function, every language, is one file too: retail.oss-vat-1.0.1.fune, 43,282 bytes, sha256 ce85841c8c38c0c8e1ec067733af5d541e14881cde2145cd59fd209bd1cf04ed. It installs into a project of any language.

// fune: before retail.oss-vat

// fune: after retail.oss-vat

// fune: replace money.amount in retail.oss-vat
// fune: replace money.apply-rate in retail.oss-vat

// fune: step retail.oss-vat after <n|label>

More from the author

- **Same country** as the seller: a domestic sale at that country's rate (`domestic`). - **Seller established in one EU member state, small:** while its total cross-border B2C distance sales and TBE services to other member states stay at or below EUR 10,000 in the current calendar year, and did in the previous one, it charges its own country's VAT (`origin`). The sale that takes this year's total over EUR 10,000 is already taxed at destination, which is why `euSalesThisYear` includes this supply. A seller may opt to tax at destination anyway (`optedIn`); the option binds for two calendar years. - **Otherwise**, and always for sellers established outside the EU: the customer's member state's VAT (`oss`).

VAT is `net x rate`, rounded half up to the minor unit with `money.apply-rate`. A negative net (a credit note) gives negative VAT.

## Rates are dated data

`data/oss-rules.json` holds each member state's **standard** rate from the start of OSS on 2021-07-01, with each change since on its effective date, and the EUR 10,000 threshold (in euro cents) as a dated row too. Rows that say 2021-07-01 are rates that were already in force then, not their enactment dates. Changes recorded: Luxembourg 17% to 16% for 2023 and back to 17% from 2024; Estonia 20% to 22% from 2024-01-01 and 24% from 2025-07-01; Finland 24% to 25.5% from 2024-09-01; Slovakia 20% to 23% from 2025-01-01; Romania 19% to 21% from 2025-08-01.

A build installed with `history=current` keeps only the rates in force and refuses an older date rather than answering it at today's rate.

## Not modelled

- Reduced, super-reduced and parking rates. Books, food, children's clothes and much else are taxed at reduced rates that differ by country and product; this capability knows only standard rates, so a caller selling reduced-rate goods must look the rate up by product. - Territories outside the EU VAT area (the Canary Islands, whose 7% "VAT" row appears in the Commission's database, Åland, Mount Athos and others) and the reduced rates of Madeira and the Azores. - Imports in consignments up to EUR 150 (the Import One Stop Shop, IOSS), Northern Ireland sellers (XI), and deemed-supplier rules for marketplaces. - Converting sales totals into euros: pass the thresholds in EUR, converted as the member state of identification requires.

## Sources

- Standard rates: European Commission, Taxes in Europe Database (TEDB), queried through its VAT retrieval service (https://ec.europa.eu/taxation_customs/tedb/ws/, WSDL VatRetrievalService.wsdl) on 2026-09-23 for all 27 member states, from 2021-07-01 to 2026-09-23. Human-readable entry point: https://taxation-customs.ec.europa.eu/taxation/vat/vat-directive/vat-rates_en (links to TEDB, https://ec.europa.eu/taxation_customs/tedb/). The database returned semi-annual snapshots; the change dates above are the effective dates of the national measures, each confirmed by the snapshots either side. The latest snapshot the service returned is 2026-07-01 for most states, 2026-01-01 for Cyprus and Portugal and 2025-01-01 for Greece; their rates are assumed unchanged since, and should be re-checked before publishing. - Threshold: Council Directive 2006/112/EC (the VAT Directive), article 59c, as amended by Council Directive (EU) 2017/2455; the application date was moved to 1 July 2021 by Council Decision (EU) 2020/1109. The Commission's "Guide to the VAT One Stop Shop" (section on the EUR 10 000 threshold) states the rule used here: one threshold for TBE services and intra-EU distance sales together, net of VAT, current and preceding calendar year, for suppliers established in only one member state: https://vat-one-stop-shop.ec.europa.eu/system/files/2021-07/OSS_guidelines_en.pdf and the list of legal acts at https://vat-one-stop-shop.ec.europa.eu/vat-e-commerce/eu-legislation_en

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

Files