Gift Aid¶
Gift Aid is a UK tax relief that allows charities to reclaim 25% on donations from UK taxpayers. Badger Commerce automates the collection of Gift Aid declarations, tracking of eligible donations, and submission of claims to HMRC.
Overview¶
The Gift Aid system has three main components:
- Declaration Collection — customers declare Gift Aid eligibility at checkout, via their account, or from the chaser email
- Donation Tracking — donations are recorded with tax period, donor details, and Gift Aid status
- HMRC Submission — a scheduled job submits eligible donations to HMRC and tracks results
Charity plan only
Gift Aid is sold on the Badger Sett Charity plan (and Enterprise), not on the self-serve Lite plans. On a plan without it, donations are still taken but no declaration is recorded and the site's HMRC claim is skipped. Shops with no Sett subscription record keep Gift Aid. See Subscription Entitlements.
Declaration wording¶
The tickbox text (giftaid.acceptanceLink) and the declaration (giftaid.acceptanceText) are site
messages. The default declaration names the charity with a {siteName} placeholder, filled with the
site's name. Override either message in Site Text to change the wording; {siteName} still works in an
override.
Data Model¶
Donation¶
Represents a single donation made through an order or subscription invoice.
A donation from an order is its line's charged price (amount, in pence), never its quantity: a
£25 web donation (25 × £1) and a £5.50 donation taken at the till (one line at 550, see
Prices set at the till) are both recorded at what was given.
| Field | Description |
|---|---|
giftAidDeclaration |
Whether Gift Aid can be claimed on this donation |
giftAidDeclarationRef |
ID of the GiftAidDeclaration that covers this donation |
giftAidTitle/Forename/Surname |
Donor name (required for HMRC claim) |
giftAidHouseNumber/Postcode |
Donor address (required for HMRC claim) |
taxPeriod |
UK tax year in YYYY/YY format (e.g. 2024/25) |
submittedToHMRCDate |
Set when the donation is successfully submitted to HMRC |
submittedAmount |
What was actually sent to HMRC, in pence — captured when the claim XML is built |
refundedAmount |
Cumulative amount of this donation, in pence, refunded to the donor |
refundedDate |
When the refunded amount last changed |
giftAidAdjustmentPence |
Claimed donation value since refunded — the charity owes HMRC this back |
giftAidAdjustmentDate |
When the donation was first flagged as needing an adjustment |
externalId |
Links to the originating order ({orderId}_{lineItemId}) or invoice (invoice_{stripeInvoiceId}) |
Two derived amounts matter when reading this entity:
claimableAmount=amount - refundedAmount, floored at zero. This — notamount— is what goes to HMRC and what the claim totals are built from.giftAidAdjustmentRequired=giftAidAdjustmentPence > 0.
GiftAidDeclaration¶
A donor's declaration that they are a UK taxpayer. Matched to donations by the donor's account (owner) under the same name, or by ownerKey: see Which declaration covers a donation.
| Field | Description |
|---|---|
ownerKey |
Composite key: lowercase forename+surname+houseNumber+postcode |
owner |
User ID of the person who made the declaration |
title/forename/surname/houseNumber/postcode |
Donor details |
A declaration covers: - All future donations from the same donor - All past donations from the same donor made within 4 years of the declaration date
Which declaration covers a donation¶
A guest who later signs in with an emailed code gets their guest orders on their account, and the
donations in them and the declarations made with them move too (DonationService.claimForOrders), so
the rules below then treat them as the account's.
DonationService.findCoveringDeclaration decides this, and every path uses it: new order
donations (DonationManager), subscription payments (InvoiceServiceImpl), the monthly claim run
(GiftAidSubmissionScheduler) and the repair job (GiftAidDeclarationChecker). A declaration is
the donor's when either:
- it was made on the donor's account (
owner) under the same name (compared ignoring case and spaces), at any address, or under any name when the donation has no name yet. A donor who moves, or whose card carries an old billing address, is still covered; HMRC doesn't ask for a new declaration when someone moves. The name check keeps a declaration personal, so someone else giving through a shared account isn't covered by it. - or its
ownerKeymatches the donation's name and address, which covers donations with no account (guest checkout).
When the covering declaration is found and the donation has no name or no address (a Stripe
invoice saved without a billing address, say), the gap is filled from the declaration
(DonationService.fillDonorDetailsFromDeclaration), so the claim can still be made. Details the
donation already has are kept. Nothing is claimed without a name, house and postcode.
When a subscription invoice is first synced, InvoiceServiceImpl marks it Gift Aid eligible from a
declaration on the payer's account in the same way, under the name the payment will carry (the
account's personal details, else the Stripe customer name).
A subscription payment (a donation whose externalId starts invoice_) is only given Gift Aid on a
plan with Gift-Aided regular giving (Capability.REGULAR_GIVING). The claim run and the repair job
leave such payments alone on a plan without it, whatever declaration covers them.
Because the monthly claim run checks every unsubmitted donation this way, a donation that was wrongly left without Gift Aid is picked up on the next run, within the 4-year claim window.
GiftAidSubmissionRun¶
Represents a single execution of the scheduled submission job.
| Field | Description |
|---|---|
siteId |
The site this run processed |
taxPeriodsScanned |
List of tax periods checked (e.g. [2024/25, 2023/24, 2022/23, 2021/22]) |
totalDonationsFound |
Total eligible donations found across all periods |
totalDonationsSubmitted |
Total successfully submitted to HMRC |
newlyEligibleCount |
Donations that became eligible via retrospective declarations |
submissionCount |
Number of HMRC submissions created (one per tax period with donations) |
status |
RUNNING, SUCCESS, PARTIAL, FAILED, or NO_DONATIONS |
GiftAidSubmission¶
An individual HMRC submission for a specific tax period, created during a run.
| Field | Description |
|---|---|
runId |
Links to the parent GiftAidSubmissionRun |
taxPeriod |
The tax period this submission covers |
donationIds |
IDs of donations included in this submission |
donorCount |
Number of unique donors |
totalAmountPence |
Total donation amount in pence |
status |
PENDING, SUCCESS, or FAILED |
correlationId |
HMRC correlation ID for polling/recovery |
pollEndpoint |
HMRC-provided endpoint URL for polling |
pollAttemptCount |
Number of poll attempts made |
lastPollAttempt |
Timestamp of the last poll attempt |
hmrcPollIntervalSeconds |
HMRC-suggested poll interval |
statusLog |
Timestamped log of all state changes (created, submitted, polled, failed, etc.) |
requestXml |
Raw XML sent to HMRC (test mode only) |
responseXml |
Raw XML response from HMRC (test mode only, or on error) |
Scheduled Processing¶
GiftAidSubmissionScheduler (worker module)¶
The scheduler runs on the 7th of every month at 9:00 AM UK time (0 0 9 7 * *). Each execution:
- Iterates all active sites with a configured charity reference and gateway credentials
- Creates a
GiftAidSubmissionRunto track the overall execution - Scans 4 tax periods back from the current date
- For each tax period, fetches all unsubmitted donations (
submittedToHMRCDateis null) - Validates donor postcodes — formats to uppercase with space before final 3 characters (e.g.
de723ul→DE72 3UL) - Checks eligibility for each donation:
- If
giftAidDeclaration=true— already eligible - If
giftAidDeclaration=false— looks for a declaration that covers it (by account and name, or by name and address). If one does, a missing name or address is filled from it and the donation is updated togiftAidDeclaration=truewithgiftAidDeclarationRefset - Runs pre-submission validation via
DonationValidator— donations with issues are skipped and flagged - Submits eligible donations to HMRC grouped by tax period (one R68 v2 claim per period)
- Updates the run with final stats and status
GiftAidPollScheduler (worker module)¶
Polls HMRC for the status of PENDING submissions. Runs every 60 seconds (configurable via hmrc.giftaid.poll-interval-ms).
- Finds all PENDING submissions with a correlation ID
- Checks backoff timing — uses HMRC-provided poll interval, or exponential backoff: 1m, 5m, 15m, 30m, then hourly
- Polls HMRC via the correlation ID
- On success: marks submission as SUCCESS, sets
submittedToHMRCDateon donations, sends DELETE to HMRC Transaction Engine (DSP protocol requirement), sends admin notification email and closes the shop's failed-claim incident if one is open - On still processing: updates poll count and waits for next interval
- On failure: marks submission as FAILED with error message
- After 24 poll attempts: marks as FAILED (gave up)
Every claim that ends FAILED is reported: see When a claim fails.
GiftAidRetryListener (worker module)¶
Listens on RabbitMQ (giftaid-retry queue) for retry requests from the admin UI.
- Loads the original failed submission
- Filters donations to only those not yet submitted (in case some were submitted via another path)
- Creates a new PENDING submission record
- Submits to HMRC — if accepted immediately, marks SUCCESS and sends the admin notification email; if acknowledgement, stays PENDING for poll scheduler; if it fails, it is reported like any failed claim
Retrospective Declarations¶
A key feature is handling retrospective Gift Aid declarations. When a donor makes a declaration, it covers past donations up to 4 years back. The scheduler handles this automatically:
- Every run scans all unsubmitted donations (not just those with
giftAidDeclaration=true) - Donations without a declaration are checked against existing declarations, by account and name or by name and address
- If a matching declaration is found, the donation is flagged as eligible and included in the submission
- The run tracks how many donations became
newlyEligiblethis way
Admin Notification Email¶
When HMRC accepts a claim (GiftAidPollScheduler), GiftAidNotificationService emails the
address in giftaid-admin-notification-email. Staff can send it again from the claim's page in the
admin (Resend email). Nothing is sent when the setting is empty.
It's a Badger email, not one of the shop's: it's named Badger Commerce (at the shop's own from-address) and laid out in Badger's own style (see Badger's own emails). It shows:
- the Gift Aid reclaimed (25% of the donations, to the penny), in the subject line and at the top
- the tax year, the number of donations, the total donated and the date the claim was sent
- the HMRC reference (the submission's
correlationId), when the claim has one - a See this claim button to the claim's own page,
/admin/donations/hmrc-submissions/submission/{id}
Amounts are always in pounds, whatever the shop sells in. The text comes from the
giftAidClaimEmail.* keys. Templates: templates/platform/email/giftaid/claimAccepted.html and
claimAccepted-text.html in commerce-core.
When a claim fails¶
A claim ends FAILED when HMRC rejects it, never gives a final answer (24 polls), or never receives
it (no correlation ID, at once or found stale by the next run), whether it came from the monthly
run or from Retry. GiftAidNotificationService.claimFailed reports it as an incident for the
shop, not a message per failure, so a claim retried five times is one alert, not five:
- Opens on the shop's first failed claim. Badger is told in Slack (
#badger-notifications: shop, tax year, donations and amounts, HMRC's message, submission and correlation IDs, whether the shop was emailed, and a "To fix" line when HMRC refused the shop's Gateway sign-in). The shop's Gift Aid contact (giftaid-admin-notification-email) gets the Gift Aid claim not accepted email, a Badger email like the accepted one (platform/email/giftaid/claimFailed): the Gift Aid not yet claimed, the claim's figures, what went wrong (the submission'sresponseMessage), what happens next, and a See this claim button to the claim's page, where Retry is. With no address set, only Badger is told. When HMRC refused the Government Gateway sign-in (GovTalk error 1046, "Authentication Failure", the one failure only the shop can put right) the email is headed "HMRC refused your Government Gateway sign-in", in the subject too, and tells them to enter the current HMRC Gateway username and password under Settings › Gift Aid and press Retry. - Stays quiet while it is open: a retry that fails again, or another tax year's claim failing, is recorded on the submission as before but nobody is told again.
- Closes when every tax year that had a failed claim has since had a claim accepted
(
claimAccepted). Badger is told in Slack how long it lasted; the shop gets the usual claim accepted email for each claim.
The open incident is kept in Redis by GiftAidClaimIncidents (giftaid-claim-incident:<siteId>,
when it opened, and giftaid-claim-incident:<siteId>:tax-years, the tax years still failing), for
27 days: a shop still failing at the next monthly run is reported afresh. With Redis down every
failed claim is reported. The run itself is no longer reported separately: a FAILED or PARTIAL
run is its failed claims.
Gift Aid chaser email¶
A shop can email donors who gave without Gift Aid, a week later, asking whether they're able to add it. It is
off until the shop turns it on: Settings › Fundraising and Gift Aid › Gift Aid › Gift Aid chaser email
(giftaid-chaser-enabled). Whether a shop needs marketing consent to send it is the shop's own
decision; the setting's help text points them to the ICO's guidance on fundraising emails.
What the donor gets. One email (shop design, template templates/shop/email/giftAidChaser.html),
worded as a question, since not everyone pays enough UK tax to add Gift Aid: thanks for the
donation, that no declaration was found on file for them, what Gift Aid would add (25%) if
they're able to, and, when their donations in the claim window come to more, what it would add on
all of them. It invites a donor who thinks they have already declared to reply.
Replies go to the shop's inbox. With email replies on,
each chaser email carries its own reply address, g-<code>@reply.bdgr.co.uk
(GiftAidChaserInboundHandler). The donor's first reply opens a conversation in Customers ›
Messages, from the donor's address, about the donation (linked to it, labelled Gift Aid email:
donation on 3 Nov 2026), and the shop is told as for any new enquiry. Further replies to the same
email go into that conversation, and staff answer from it as usual. An out-of-office reply opens
nothing. With email replies off for the deployment or the shop, replies go to
giftaid-chaser-reply-to, else the Gift Aid admin email, else the sender address. The Add Gift Aid
button opens /giftaid/declare/{token}, which works without signing in:
- It lists the donations and the Gift Aid, fills in the donor's name from the donation, and asks for their house number or name and postcode. It never shows the address Badger has, since anyone with the link (a forwarded email) can open the page.
- Yes, add Gift Aid saves a declaration (
sourceCHASER) under the name and address typed in, claims the donations the email asked about under them, and also covers the donor's other donations when they have an account. The declaration'sownerKeycovers guest donors' later gifts. - No thanks, don't ask me again means that donor is never sent a chaser again. A mail app's own
unsubscribe button (
List-Unsubscribe, one-click) does the same. - Opening the link changes nothing: mail scanners open links, so only the buttons act.
- The link works for 90 days. After that the page says it has run out and points to the account's Donations page.
- It stays open while a shop is paused.
Who is asked. GiftAidChaserJob (worker, daily at 10:30 UK time, one worker at a time) calls
GiftAidChaserService.chaseSite for every shop. A donation is chased when:
- the shop is open (not paused or archived), has the chaser on, its plan includes Gift Aid, and its HMRC charity reference is filled in;
- it has no Gift Aid, hasn't been sent to HMRC, isn't fully refunded, and no declaration covers it;
- it's a one-off donation, or a subscription payment on a plan with Gift-Aided regular giving;
- it is at least
giftaid-chaser-delay-daysold (default 7) and no more than 30 days old, so turning the chaser on doesn't email every past donor; - Badger has an email address for the donor: their account's when they have one, else the order's (till donations usually have none);
- the address isn't on the do-not-email list, the donor hasn't been chased in the last 365 days, has never declined, and has no declaration on their account.
Donations are grouped by the donor's address, so a donor who gave three times gets one email covering all three. A day the job didn't run is picked up the next day.
What's recorded. One giftAidChasers document per email sent: the site, donorKey (the
do-not-email list's keyed hash of the address, never the address), the donation ids, when it was
sent, and the outcome (SENT, DECLARED with the declaration id, or DECLINED). It isn't copied
by site transfer and is deleted with the site. Log lines carry ids only.
The Donations admin shows the last 90 days (emails sent, donors who added Gift Aid, donors who declined) while the chaser is on, and the Gift Aid declarations list says where each declaration was made (at checkout, on the donor's account, or from the chaser email; older ones say Not recorded).
| Key | Default | Description |
|---|---|---|
giftaid-chaser-enabled |
false |
Send the chaser email |
giftaid-chaser-delay-days |
7 |
Days after a donation before it is chased |
giftaid-chaser-from-address |
none | Sender; the order confirmation sender when empty |
giftaid-chaser-from-name |
site name | Sender name |
giftaid-chaser-reply-to |
none | Where replies go; the Gift Aid admin email when empty |
giftaid-chaser-subject |
"A quick question about your donation" | Subject line |
The worker's badger.giftaid.chaser-enabled (default true) and badger.giftaid.chaser-schedule
(default 0 30 10 * * *, UK time) switch the job off or move it for every shop.
Deduplication¶
- Donations are only submitted once —
submittedToHMRCDateis set on success - The query
findUnsubmittedDonationsByTaxPeriodAndSiteIdonly returns donations wheresubmittedToHMRCDateis null - Fully refunded donations are skipped by the scheduler and the retry listener, and partially refunded ones are claimed at their
claimableAmount - Stale
PENDINGsubmissions are automatically marked asFAILED(configurable viahmrc.giftaid.pending-stale-minutes, default 30) - The HMRC correlation ID is saved on the
GiftAidSubmissionrecord immediately after the API call, enabling crash recovery. The GovTalk XML protocol does not support client-side idempotency tokens — the PENDING→correlationId→SUCCESS/FAILED flow is the recovery mechanism
Refunds¶
HMRC only lets a charity reclaim tax on money the donor actually gave, so refunding an order that
carried a Gift Aid donation has to change the claim. GiftAidRefundService (interface in common,
GiftAidRefundServiceImpl in commerce-core) does that reconciliation.
How a refund is attributed to the donation¶
Refunds on this platform are amounts, not line selections — none of the three refund paths lets an operator pick which lines to refund. The rule is therefore:
The non-donation value of the order absorbs the refund first. Only what is left over reduces the donations, oldest line item first.
So refunding the goods and keeping the donation leaves the claim untouched, which is the usual case. Refunding more than the goods were worth eats into the donation by the excess. A donation is never pushed below zero, and any remainder beyond the order's donation value is ignored.
The alternative — pro rata across every line — was rejected: it would reduce a claim on money the donor never got back, under-claiming on genuine donations and manufacturing spurious HMRC adjustments on donations that were already claimed.
What happens next depends on whether HMRC already has it¶
| Donation state | Effect of the refund |
|---|---|
Not claimed (submittedToHMRCDate null, no live submission) |
refundedAmount rises, so claimableAmount falls. The next claim either omits the donation (full refund) or carries the reduced figure (partial refund). |
Claimed (submittedToHMRCDate set) or in flight (a PENDING/SUCCESS GiftAidSubmission lists it) |
Same amount bookkeeping, plus giftAidAdjustmentPence is set to submittedAmount - claimableAmount. The claim already sent to HMRC is never rewritten. |
An in-flight (PENDING) claim counts as claimed: the XML has already gone to HMRC, so the money is
as good as claimed and the adjustment is owed.
giftAidAdjustmentPence is the donation value that must come out of a later claim, not the tax
on it. Multiply by the Gift Aid rate to get the cash the charity owes HMRC.
Idempotency¶
The amount passed to reconcileRefund is the payment provider's cumulative refunded total for
the order, never the size of one refund. refundedAmount is set to that absolute figure and only
ever ratchets upward, so the same refund arriving twice — the admin pipeline and the Stripe
charge.refunded webhook both fire for an admin refund — cannot compound, and a stale webhook
carrying a lower total is ignored.
Reconciliation never throws: the money has already moved at the payment provider, so a Gift Aid bookkeeping failure is logged, not propagated.
Refund entry points¶
| Entry point | Module | Cumulative total passed |
|---|---|---|
RefundOrderChargeProcessor (the refundOrder pipeline, used by admin fulfilment and POST /admin/orders/{id}/refund) |
commerce-core | paymentDetails.refundedAmount after the refund is added |
ChargeRefundedHandler (Stripe charge.refunded webhook) |
worker | charge.amountRefunded |
PosRefundServiceImpl (till refunds) |
commerce-core | The charge's refunded total, re-read from Stripe |
Spotting adjustments¶
Flagged donations are listed at /admin/donations?filter=gift-aid-adjustment ("HMRC Adjustments"),
badged in the donations table, and shown on the donation detail page with the amount to deduct from
the next claim. Acting on it is a manual step — the platform does not send HMRC an adjustment.
Configuration¶
Application-level (worker application.yml)¶
These are the Badger ISV credentials for the HMRC GovTalk gateway:
hmrc:
giftaid:
vendor-id: ${HMRC_VENDOR_ID:7985}
product-name: ${HMRC_PRODUCT_NAME:Badger Commerce}
product-version: ${HMRC_PRODUCT_VERSION:1.0}
pending-stale-minutes: ${HMRC_PENDING_STALE_MINUTES:30}
poll-interval-ms: ${HMRC_POLL_INTERVAL_MS:60000}
Global Configuration (System > Global Config)¶
| Key | Description |
|---|---|
giftaid-hmrc-test-mode |
Enable/disable HMRC test mode (uses test gateway endpoint) |
Site-level Configuration (Site > Config > giftaid-config)¶
| Key | Type | Required | Description |
|---|---|---|---|
giftaid-charity-reference |
text | Yes | HMRC Charity Reference (e.g. XR12345). Sites without this are skipped. |
giftaid-gateway-username |
secret | Yes | Government Gateway username (SenderID) for HMRC submissions |
giftaid-gateway-password |
secret | Yes | Government Gateway password |
giftaid-org-name |
text | Yes | Charity organisation name as registered with HMRC |
giftaid-sender-type |
dropdown | Yes | HMRC sender type (default: Company). Options: Individual, Company, Agent, Bureau, Partnership, Trust, Employer, Government, Acting in Capacity, Other |
giftaid-regulator-name |
dropdown | Yes | Charity regulator (default: CCEW). Options: CCEW, OSCR, CCNI |
giftaid-regulator-number |
text | Yes | Charity registration number with the regulator |
giftaid-official-forename |
text | Yes | Forename of the authorised official for Gift Aid claims |
giftaid-official-surname |
text | Yes | Surname of the authorised official |
giftaid-official-postcode |
text | Yes | Postcode of the authorised official |
giftaid-official-phone |
text | Yes | Phone number of the authorised official |
giftaid-admin-notification-email |
text | No | Email address for submission notifications |
HMRC Integration¶
R68 v2 GovTalk XML Gateway¶
The implementation uses the HMRC GovTalk XML gateway with the R68 v2 schema (http://www.govtalk.gov.uk/taxation/charities/r68/2):
- Test endpoint: https://test-transaction-engine.tax.service.gov.uk/submission
- Live endpoint: https://transaction-engine.tax.service.gov.uk/submission
Submission flow: 1. Build R68 v2 XML with AuthOfficial, Declaration, Claim (OrgName, HMRCref, Regulator, Repayment with GAD entries, EarliestGAdate) 2. Calculate IRmark — SHA-1 hash of the C14N-canonicalised Body element (IRmark element removed before hashing) 3. Insert IRmark value into XML 4. POST to submission endpoint 5. Parse response — if acknowledgement, save correlation ID for polling; if error, mark FAILED 6. Poll scheduler picks up PENDING submissions and polls HMRC until success/failure 7. On final response, send DELETE request to HMRC Transaction Engine (DSP protocol requirement)
IRmark calculation:
- Canonicalise the <Body> element (including tags) using C14N without comments
- Remove all <IRmark> elements (wildcard namespace) before canonicalisation
- SHA-1 hash the canonical bytes, Base64-encode
- Verified against HMRC's official valid sample (CharitiesValidSamples.zip)
Future: HMRC Developer Hub REST API¶
An application has been registered on the HMRC Developer Hub (Application ID: 68b03431-6489-4fbb-8b7c-910563b17eda). Migration to the modern REST API with OAuth2 authentication is planned.
Creating Donations from Orders¶
Donations are created in the worker when an order is submitted: DonationProcessingEventListener takes the order-submitted event from the order-events-donations queue and passes the order to DonationManager, which creates a Donation for each donation line and a GiftAidDeclaration where the donor opted in.
DonationReconciliationJob (worker module)¶
A nightly backstop for orders whose event failed (the listener logs the failure and the message is not retried):
- Runs at 02:45 (badger.giftaid.donation-reconcile-schedule, default 0 45 2 * * *)
- Goes over every site's orders in SUBMITTED, PACKING, DISPATCHED or DELIVERED placed in the last 7 days (badger.giftaid.donation-reconcile-lookback-days), leaving the last hour to the listener
- Runs them through the same DonationManager.processOrder, which skips any line that already has a donation, so nothing is created twice
- Logs a warning per site when it creates a missed donation; a quiet night logs nothing
- Takes a Redis lock (donation-reconcile) so only one worker runs it; turn it off with badger.giftaid.donation-reconcile-enabled: false
GiftAidDeclarationChecker (commerce-core)¶
Shared service for checking and fixing Gift Aid declarations:
- Handles both order-based and invoice-based (subscription) donations
- Populates missing donor details from orders, invoices, or user profiles
- Checks for declarations that cover the donation, retrospective or not, with DonationService.findCoveringDeclaration
Admin UI¶
Navigate to Donations > HMRC Submissions (/admin/donations/hmrc-submissions):
- Run list — shows all scheduled runs with status, donations found/submitted, and newly eligible count
- Run detail — shows per-period HMRC submissions within a run
- Submission detail — shows individual donations, status log timeline, request/response XML (test mode), and retry button for failed submissions
Other donation views:
- /admin/donations — all donations
- /admin/donations/giftaid — donations with Gift Aid
- /admin/donations/current-tax-year — current tax year donations
- /admin/donations/pending-hmrc — Gift Aid donations not yet submitted
- /admin/donations/submitted-hmrc — donations already submitted to HMRC
- /admin/donations?filter=gift-aid-adjustment — donations refunded after their Gift Aid was claimed, which need adjusting out of a later claim
- /admin/donations/validation-issues — donations whose Gift Aid details fail HMRC validation
- /admin/donations/declarations — Gift Aid Declarations list (name, house number, postcode, account, where it was made), newest first. The Account column shows the owning user's email address, linked to their admin profile; declarations whose owner no longer resolves to a user on this site show the raw id in grey. Free-text search matches forename, surname and postcode, and also resolves the term against user email/name so searching by account email works.
Key Files¶
| File | Module | Purpose |
|---|---|---|
Donation.java |
common | Donation entity |
GiftAidDeclaration.java |
common | Declaration entity |
GiftAidSubmission.java |
common | Per-period HMRC submission entity (with statusLog) |
GiftAidSubmissionRun.java |
common | Scheduled run entity |
GiftAidRetryEvent.java |
common | Retry event model for RabbitMQ |
GiftAidKeyGenerator.java |
common | Owner key generation, tax period calculation, declaration validation |
DonationValidator.java |
worker | Pre-submission validation of donor fields |
GiftAidSubmissionScheduler.java |
worker | Scheduled HMRC submission job (7th of each month, 9 AM UK) |
GiftAidPollScheduler.java |
worker | Polls HMRC for pending submission results |
GiftAidRetryListener.java |
worker | Handles admin retry requests via RabbitMQ |
DonationProcessingEventListener.java |
worker | Creates donations when an order is submitted |
DonationReconciliationJob.java |
worker | Nightly backstop for donations the listener missed |
GiftAidChaserJob.java |
worker | Daily run of the Gift Aid chaser email |
GiftAidChaserServiceImpl.java |
commerce-core | Who is chased, the email, and the declaration page's actions |
GiftAidDeclareController.java |
web-mvc | The page behind the chaser email's link |
GiftAidDeclarationChecker.java |
commerce-core | Shared eligibility checking |
GiftAidNotificationService.java |
commerce-core | Claim accepted and claim not accepted emails, and the Slack reports |
GiftAidClaimIncidents.java |
commerce-core | Whether a shop has failed claims outstanding, so a failure is reported once |
GiftAidRefundService.java |
common | Refund-to-claim reconciliation contract |
GiftAidRefundServiceImpl.java |
commerce-core | Reduces or flags donations when an order is refunded |
HmrcGiftAidClient.java |
worker | HMRC GovTalk XML client (R68 v2) |
IRMark.java |
worker | IRmark calculation (C14N + SHA-1) |
DonationAdminController.java |
web-admin | Admin UI controller |