charity.gift-aid

def gift_aid(donation: Money, on_date: str) -> GiftAid

@dataclass(frozen=True)
class GiftAid:
    """A donation, the tax on it the charity reclaims, and the two together."""

    donation: Money
    #: donation x rate / (100% - rate), rounded down to the penny
    tax_reclaimable: Money
    #: donation plus taxReclaimable: the grossed up amount
    gross: Money
    #: the UK basic rate for the tax year, 2000 = 20%
    basic_rate_basis_points: int

from fune.charity.gift_aid import gift_aid  # charity.gift-aid@^1

import re

from .charity_gift_aid_data import BASIC_RATE, BASIC_RATE_HISTORY  ← this capability’s own data, compiled from data/basic-rate.json into the same file by fune build
from .charity_gift_aid_types import GiftAid
from .math_round_div import round_div  ← from math.round-div ^1.0.0 · built alongside by fune
from .money_amount import Money, money  ← from money.amount ^1.0.0 · built alongside by fune

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


def _basic_rate(on_date: str) -> int:
    for row in BASIC_RATE:
        if row.valid_from <= on_date and (row.valid_to is None or on_date <= row.valid_to):
            return row.basis_points
    # A history=current build carries only the rate in force; answering an old
    # gift with today's rate would be a quiet wrong claim, so say why instead.
    if BASIC_RATE_HISTORY != "full" and len(BASIC_RATE) > 0:
        earliest = min(row.valid_from for row in BASIC_RATE)
        if on_date < earliest:
            raise ValueError(
                "no Gift Aid basic rate on %s: this build was installed with history=%s, so it only carries rules from %s. "
                "Reinstall with history=full for earlier tax years." % (on_date, BASIC_RATE_HISTORY, earliest)
            )
    raise ValueError("no Gift Aid basic rate on %s" % (on_date,))


def gift_aid(donation: Money, on_date: str) -> GiftAid:
    """The tax a charity reclaims on a Gift Aid donation. The donor is treated
    as having given the gift after deducting basic rate tax (ITA 2007 s414), so
    the charity reclaims donation x rate / (100% - rate): 25p per £1 at 20%.
    It is always the UK basic rate, for Scottish and Welsh taxpayers too.
    """
    if donation.currency != "GBP":
        raise ValueError("Gift Aid is claimed in GBP, received %s" % (donation.currency,))
    if donation.minor < 0:
        raise ValueError("donation must not be negative, received %d" % (donation.minor,))
    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,))
    rate = _basic_rate(on_date)
    # Rounded down: a claim may never exceed the tax treated as deducted.
    tax = round_div(donation.minor * rate, 10000 - rate, "down")
    return GiftAid(
        donation=money(donation.minor, "GBP"),
        tax_reclaimable=money(tax, "GBP"),
        gross=money(donation.minor + tax, "GBP"),
        basic_rate_basis_points=rate,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 2 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 charity.gift-aid

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./charity.gift-aid-1.0.2-python.fune, or fetch it from a terminal with fune pull charity.gift-aid@1.0.2:python.

The whole function, every language, is one file too: charity.gift-aid-1.0.2.fune, 18,560 bytes, sha256 09899aa21a9b970e077beb12a42deb66e9f6710f0beffa59f313fac439e4c65e. It installs into a project of any language.

# fune: before charity.gift-aid

# fune: after charity.gift-aid

# fune: replace math.round-div in charity.gift-aid
# fune: replace money.amount in charity.gift-aid

# fune: step charity.gift-aid after <n|label>

More from the author

## Decisions

- **Always the UK basic rate.** Since 6 April 2018 s414 and s415 refer to "the basic rate", not the Scottish or Welsh basic rate, so a Scottish taxpayer's gift is grossed up at the same 20% as anyone else's. Any difference between a devolved basic rate and the UK one is settled with the donor through s414A, never through the charity's claim. - **Rounded down to the penny.** The tax treated as deducted is exact; a claim may not exceed it, so a fraction of a penny is dropped. £10.01 gives 250.25p, claimed as 250p. Claim on a total rather than summing per-gift results if you want the pennies back (charity.reclaim-batch does). - **The date is the date of the gift**, which decides the tax year and so the basic rate: 22% in 2007-08 (22/78, about 28.2p per £1), 20% from 6 April 2008. - It does not check eligibility (declaration, benefits): see charity.gift-aid-eligibility. - The transitional relief of 3p per £1 paid to charities for 2008-09 to 2010-11 (Finance Act 2008 s53) was a separate government payment, not Gift Aid, and is not included.

The rates start at 6 April 2007, when ITA 2007 took over the rules; an earlier date is an error rather than a guess. A build installed with `history=current` refuses dates before the rate it carries and says why.

## Sources

- Income Tax Act 2007 ss414-415, https://www.legislation.gov.uk/ukpga/2007/3/part/8/chapter/2 (s414(2)(a) "income tax at the basic rate"; s415 grossed up "by reference to the basic rate for the tax year in which the gift is made"). - Finance Act 2007 s1 (basic rate 22% for 2007-08), https://www.legislation.gov.uk/ukpga/2007/11/section/1 - Finance Act 2008 s1 (basic rate 20% for 2008-09), https://www.legislation.gov.uk/ukpga/2008/9/section/1 - GOV.UK, "Income Tax rates and Personal Allowances" (basic rate 20% for 2026-27), https://www.gov.uk/income-tax-rates - GOV.UK, "Claim top-up payments for the Gift Aid Small Donations Scheme" ("If the basic rate of Income Tax is 20% ... a donor gives £30, you can claim ... £7.50"), https://www.gov.uk/guidance/claiming-a-top-up-payment-on-small-charitable-donations

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/).

Legislation: Crown copyright and database right.

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

Files