Skip to content
allanninal.dev/build
Collaborate

Part 1 of 7 · Gift Aid claimer series ~6 min read

A Gift Aid claimer on AWS for a few dollars a month

The finance trustee reports that the charity claimed thirty-five thousand seven hundred pounds of Gift Aid last year, which sounds like a job well done. It took an afternoon with the donation export to work out that another eight thousand nine hundred and twenty-five was available and went unclaimed, and that not one pound of it was refused by HMRC. Nobody asked.

a close up of a typewriter with a donation sign on it
Photo by Markus Winkler on Unsplash

Key takeaways

  • A donation is claimable or not at the moment it is made, not when you notice.
  • A declaration must be in force on the donation date. Signed later covers later.
  • Small cash gifts have their own route, and it is capped by your ordinary claim.
  • The claim is easy. The evidence that survives an audit is the system.
  • Designed on AWS for about $2 a month.

The whole system on one page

Before any code, here is the shape of what we are designing.

System: declarations, donations and scheme rules joined into a claimThree boxes across the top sit outside the AWS account. On the left, Declarations from forms, web and verbal, each with a date. In the middle, Donations from bank, card, cash and contactless. On the right, The schemes: rates, limits and the matching rule. Each connects by an arrow to the AWS account container below, labelled once per donor, continuous, and rarely. Inside the AWS account are three components in a row. Donor record: who signed what, and from when. Routing: Gift Aid, small donations, or neither. And Claim and evidence: what was claimed and on what basis. A note says the middle box is the whole job, and everything either side of it already exists in the charity somewhere, usually in two systems that have never been joined.AWS ACCOUNTDeclarationsforms, web, verbal --each with a dateDonationsbank, card, cash,contactlessThe schemesrates, limits andthe matching ruleDonor recordwho signed what,and from whenRoutingGift Aid, smalldonations, neitherClaim and evidencewhat was claimed,and on what basisonce per donorcontinuousrarelyThe middle box is the whole job. Everything either side of it already exists in the charity somewhere, usually in two systems that have never been joined.
Fig 1. Three things outside the account, three pieces inside it. The routing in the middle is where the money is won or lost.
  • App integration
  • Security & identity
  • People

Why the money goes missing

Gift Aid is not difficult in the way tax is difficult. The rate is twenty-five per cent, it applies to almost every donation from a UK taxpayer, and HMRC pays it without argument. What it needs is a piece of evidence that existed at the moment the donation was made, and charities are organised around receiving money rather than around dating paperwork.

So the donation arrives in one system and the declaration sits in another, and nothing joins them until somebody exports both to a spreadsheet once a year. By then the donor who gave forty pounds in March and never signed anything is a name on a list that nobody is going to phone.

What runs (the inside)

  • Donor record. Every declaration with the date it took effect and what it covers. Part 2.
  • Routing. Each donation matched to a donor and a scheme, or to neither, with the reason recorded. Part 3.
  • The claim. Built against the schemes’ own limits, including the one that ties small donations to ordinary Gift Aid. Part 4.
  • Evidence. The file that has to still make sense when somebody asks about it four years later. Part 5.

One charity, one year

One charity's year from donations received to Gift Aid unclaimedA horizontal row of five boxes joined by arrows. Four thousand one hundred and twenty donations totalling one hundred and eighty-six thousand four hundred pounds received. Two thousand nine hundred and five covered by a declaration in force. Thirty-five thousand seven hundred pounds claimed as Gift Aid. Six hundred and forty small gifts yielding one thousand nine hundred and seventy-five pounds under the small-donations route. And eight thousand nine hundred and twenty-five pounds lost across five hundred and seventy-five donations with no declaration. A note says the last box is not a tax outcome but five hundred and seventy-five people who gave money and were never asked to tick a box.ONE SMALL CHARITY, ONE FINANCIAL YEAR4,120 donationsGBP 186,400received2,905 covereda declaration wasin forceGBP 35,700claimed asGift Aid640 small giftsGBP 1,975 under thesmall-donations routeGBP 8,925 lost575 donations, nodeclarationThe last box is not a tax outcome. It is 575 people who gave money and were never asked to tick a box.
Fig 2. The same system as one line. The first four boxes are the job working; the fifth is the one the annual spreadsheet never produces.
  • Machine learning
  • Management
  • Analytics

In plain words

Declarations are read once each, into a record that says who the donor is, when the declaration took effect, and whether it covers past donations as well as future ones. That last field matters more than it looks, and part two is about it.

Donations arrive continuously from wherever the charity takes money, and each one is matched to a donor. A donation with no matching donor is not an error; it is a cash gift in a bucket, and it may still be worth something under the small-donations route.

Then each donation is routed. Ordinary Gift Aid if a declaration was in force on the day it was given. The small-donations scheme if it is small, in cash or contactless, and within that scheme’s annual allowance. Neither, if it is a large donation from somebody who never signed — and that case is counted and reported rather than dropped, because it is the number that changes what the charity does next year.

The claim is then arithmetic against published limits, and the evidence file is assembled at the same time rather than reconstructed later.

Design rules that shaped every decision

  • A donation’s eligibility is decided by the state of the world on its own date.
  • A declaration signed today does not retroactively cover March unless it says so.
  • An unclaimable donation is counted and reported, never silently skipped.
  • The small-donations route is checked against the ordinary claim, not just its own cap.
  • Nothing is claimed on a donor flagged as not a UK taxpayer.
  • The evidence is written when the claim is made, because it cannot be rebuilt.

What it does not do

It does not file the claim. HMRC has its own route for that and it changes; this system produces the schedule that goes into it and the record of why each line is there. It does not chase donors either, though it produces the list of people worth chasing, ranked by what their missing declaration is worth.

It also does not decide whether a donor has paid enough tax. That is a fact about the donor’s own affairs which the charity cannot see and is not required to verify; what the charity must do is hold a declaration in which the donor confirms it, and act on it if they later say otherwise. The system records the confirmation and the date it was given.

The next four posts walk through each piece: how a declaration is captured and why its date decides everything, how a donation is routed, how the claim is built against the caps, and what the evidence has to contain. One diagram per post, a cost breakdown, and an engineering reference at the end.

All posts