Skip to content
allanninal.dev/build
Collaborate

Part 1 of 7 · Rebate claim tracker series ~6 min read

A rebate claim tracker on AWS for a few dollars a month

Somewhere in an inbox is a PDF that says you get two and a half percent back on everything you buy from a supplier above ninety thousand a year, rising to four percent above a hundred and forty. You bought a hundred and thirty-eight thousand. Nobody noticed until March, and the claim window closed in January.

a phone, keyboard, mouse and mouse pad on a pink surface
Photo by Jakub Zerdzicki on Unsplash

Key takeaways

  • Rebate terms belong in a rule, not in a PDF nobody opens.
  • Accrue as you buy; year-end discovery is how windows get missed.
  • Retrospective tiers pay on everything, so the last pallet is the valuable one.
  • Your figure and the supplier’s will differ, and the difference is definitional.
  • Designed on AWS for about $3 a month.

The whole system on one page

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

System: rebate agreements read into rules, accrued, and claimedThree boxes across the top sit outside the AWS account. On the left, Supplier agreements, PDFs and their annual amendments. In the middle, Your purchase ledger of invoices, credits and returns. On the right, Whoever buys, deciding this week's order. Each connects by an arrow to the AWS account container below. The agreements are read once per amendment. Every purchase line feeds in. Where you stand now goes back out. Inside the AWS account are three components in a row. On the left, Terms as rules covering tiers, dates and exclusions. In the middle, Live accrual showing what is earned so far against each tier. On the right, Claims and windows, with evidence, before they shut. A note says the arrow going back up is worth more than the claim itself because it changes what you buy while you can still buy it.AWS ACCOUNTSupplier agreementsPDFs, and theirannual amendmentsYour purchase ledgerinvoices, credits,returnsWhoever buysdeciding this week'sorderTerms as rulestiers, dates,exclusionsLive accrualearned so far,against each tierClaims and windowswith evidence,before they shutread once, peramendmentevery purchaselinewhere you stand,nowThe arrow going back up is worth more than the claim itself: it changes what you buy while you can still buy it.
Fig 1. Three things outside the account, three pieces inside it. The claim is the visible output; the feedback to the buyer is where the money actually is.
  • Analytics
  • Front-end & mobile
  • People

Why this money goes missing

Rebate income is not invoiced to you and it does not appear on a statement. Nothing arrives to remind you it exists. It is the only significant sum in a small business that has to be actively gone and got, and the only person who knows the terms is usually the one who negotiated them.

When that person changes role, the terms become a document in a folder, the accrual becomes a guess at year end, and two or three claims a year quietly expire. None of that shows up as a loss anywhere, which is precisely why it persists.

What runs (the inside)

  • Terms as rules. The agreement, once, turned into tiers, dates and exclusions a machine can evaluate. Part 2.
  • Live accrual. What you have earned so far, updated as purchases land, with the tier you are closest to. Part 3.
  • Claims and windows. What a claim has to contain to survive scrutiny, and how a window stops being missed. Parts 4 and 5.

One agreement, one year

One supplier rebate agreement across a year, from signing to claimA horizontal row of five boxes joined by arrows. Agreement signed, three tiers and a ninety-day claim window. Accruing, one thousand eight hundred and forty pounds earned by June. One pallet short, flagged in October. Tier hit, four percent on the whole year. Claimed on day twelve rather than day ninety-four. A note says the third box paid for the entire system and it is the only one that had to happen at a particular moment.ONE AGREEMENT, ONE YEARAgreement signed3 tiers, 90-dayclaim windowAccruing£1,840 earnedby JuneOne pallet shortflagged in OctoberTier hit4% on the whole yearClaimed in day 12not day 94The third box paid for the entire system, and it is the only one that had to happen at a particular moment.
Fig 2. The same system as one line. The alert in October is the part that cannot be done retrospectively, which is why it is the part worth automating.
  • Machine learning
  • Management
  • Analytics

In plain words

A supplier agreement arrives as a PDF. It is read once — properly, by a model, into structured fields — and becomes a rule: these product ranges, this period, these tiers, this claim window, these exclusions. The PDF is kept, because a claim sometimes needs the original wording, but nothing downstream reads it again.

From then on, every purchase invoice line is matched against the rules it might count towards. A line can count towards more than one agreement, and frequently does. The accrual moves as the lines land, so the number is current rather than annual.

In October, when the system can see that you are four thousand pounds of purchases short of a tier that pays retrospectively on the whole year, it says so to the person placing orders. That is a purchasing decision with about six weeks of runway, and it is the single most valuable output here.

At period end the claim is assembled with the line detail behind it, submitted inside the window rather than near the end of it, and then chased — because a submitted claim and a received credit note are separated by roughly two months and one forgotten email.

Design rules that shaped every decision

  • The agreement is read once and becomes a rule. Nothing downstream re-reads a PDF.
  • Accrue on purchase lines, not on supplier statements. Their statement arrives too late to act on.
  • A retrospective tier pays on everything, so proximity to a threshold is an alert, not a note.
  • Every accrual has to be explainable down to the invoice lines that produced it.
  • The claim window is a date with a countdown, not a field in a document.
  • Chase the credit note, not the claim. Submission is the halfway point.

What it does not do

It does not negotiate, it does not tell you whether the terms are good, and it does not buy anything. Deciding to spend four thousand pounds in November to earn six is a judgement about stock, cash and shelf life that only the buyer can make.

It also does not replace the supplier relationship. When your figure and theirs differ by nine hundred pounds, the resolution is a phone call. What the system does is make sure you arrive at that call with the line detail rather than with a number you cannot explain.

The next four posts walk through each piece: how an agreement becomes a rule, why an accrual is not a claim, what a claim needs to survive scrutiny, and how a window stops being missed. One diagram per post, a cost breakdown, and an engineering reference at the end.

All posts