build.allanninal.dev

Part 1 of 7 · Loyalty tracker series ~5 min read

A loyalty tracker on AWS for a few dollars a month

A small shop’s regulars are its lifeblood, and a points program is the simplest way to say thank you and keep them coming back. But the paper punch cards get lost, the spreadsheet never gets opened, and nobody at the counter remembers who’s close to a free coffee. This post walks through the design of a small system that runs the whole program for you: it earns points on every sale by your rules, keeps each customer’s balance exact, tells them the moment they’ve earned a reward, lets staff redeem with one tap, and gently nudges the regulars who’ve started slipping away.

Key takeaways

  • Three ways a member is created: a sign-up form, a quick add by staff, or an auto-enroll on first sale.
  • Every sale ends in one of four moves: skip, add points, add points and announce a reward, or hold for review.
  • Your rules live in a short Drive doc: points per dollar, bonus items, and what each reward costs.
  • Staff redeem with one tap, but always confirm first — nothing comes off a balance by accident.
  • Designed on AWS for about $2 a month at typical small-shop volume.

The whole system on one page

Before any code, here’s the shape of what we’re designing.

System shape: three inputs, three pieces inside AWS At the top, three external boxes in a row. Far left, "Shop sales" — the point-of-sale till that sends each completed sale (phone number or member id, basket total, and the items bought) to the loyalty tracker, plus a sign-up form and a staff quick-add lane that create new members. Centre, "Rules and rewards" — a Drive folder with a rules doc covering points per dollar, bonus items, and the reward tiers, plus a voice doc with the email message templates. Far right, "Customers" — the shop's members; emails land in their inbox telling them their new balance and when they've earned a reward. Each connects via an arrow to the AWS account container below. Shop sales has an outgoing arrow into AWS. Rules and rewards feed in to ground every points decision and every email. Customers receive emails with their new balance, how close they are to the next reward, a reward-earned note when they cross a tier, and an unsubscribe link. Inside the AWS account are three components in a row, mirroring the layout above. On the left, the Sign-up — creates a member from the form, the staff quick-add, or an unknown phone number on a sale, and writes them into the member store. In the middle, the Earn engine — runs on each sale; reads the rules; works out the points; picks one of four moves: skip, add points, add and announce a reward, or hold for review. On the right, the Redeem desk — looks the customer up, shows the reward and what it costs, takes one tap with a confirm, and takes the points off. Internal arrows flow left to right. A note at the bottom reads: every points change is logged and reversible — staff confirm each redemption so nothing is given away by mistake. Shop sales till, sign-up, quick-add Rules and rewards points, tiers, templates Customers where emails land sales in grounds balance and rewards AWS account Sign-up form, quick-add, auto-enroll on sale Earn engine picks one of four: skip, add, reward, hold Redeem desk one tap with confirm, takes points off member reward Every points change is logged and reversible — staff confirm each redemption.
Fig 1. Three inputs outside, three pieces inside AWS. Members come in from a sign-up form, a staff quick-add, and an auto-enroll on first sale. The Earn engine runs on each sale and picks one of four moves. The Redeem desk lets staff give a reward with one tap and a confirm.

What you set up once (the outside)

  • Shop sales. Your till sends each completed sale to the tracker — the customer’s phone number or member id, the basket total, and the items bought. Most modern point-of-sale systems can send this as a small web request when a sale closes; if yours can’t, a one-line script reads the day’s sales export and posts them. New members can also come in two other ways covered in Part 2 — a sign-up form a shopper fills in, and a quick-add staff do at the counter in a few seconds.
  • A rules folder. Two short Google Docs in a Drive folder. The rules doc covers how points are earned — how many points per dollar spent, which items earn bonus points (“double points on beans”), and the reward tiers (“100 points = a free coffee, 250 points = a free lunch”). The doc also holds the quiet-hours setting and how long a customer can be away before they count as lapsing. The voice doc holds the email templates — what the balance email and the reward-earned email actually say, in your shop’s own friendly tone.
  • Customers. Your members. Each has a phone number (how a sale is matched to them) and, if they gave one, an email address. Emails land with their new balance, how close they are to the next reward, a clear “you’ve earned a free coffee” note when they cross a tier, and an unsubscribe link. A customer with no email still earns points; they just check their balance at the counter.

What runs on every sale (the inside)

  • The sign-up. Three ways a member is created. A shopper fills in a short web form (name, phone, email) and lands as a member. Staff add someone at the counter in a few taps. Or a sale comes in for a phone number the system has never seen, and the earn engine creates a member on the spot so the points aren’t lost — the customer can fill in their email later. Part 2 walks through all three.
  • The earn engine. Runs on each sale. Reads the rules doc. Works out the points the sale earns — base points from the total, plus any bonus-item points. Then picks one of four moves. Skip: the sale has no member attached and no phone to match — do nothing. Add points: the normal case — add the points and update the balance. Add and announce a reward: the new balance crosses a reward tier — add the points and email the customer that they’ve earned a reward. Hold for review: something looks off (a basket far larger than this customer ever buys, or a refund that would push points negative) — park it for a staff member to check. The earn engine calls no model; the math is plain Python.
  • The redeem desk. A simple lookup screen for staff. Type a phone number, see the customer, their balance, and any reward they can claim. Staff tap the reward, the screen shows what it costs in points, staff press Confirm, and the points come off. The system checks the balance is high enough first, locks the customer so the same reward can’t be redeemed twice in two seconds, and writes the redemption to the ledger. A nightly email goes to anyone whose balance changed that day, and a weekly sweep finds regulars who’ve gone quiet so they can be nudged. A monthly summary writes the owner a short plain-English read on how the program is doing.

In plain words

Maria buys a coffee and a bag of beans on Tuesday morning, $18 total. She joined the program last month, so her phone number is on file. The till sends the sale; the earn engine reads the rules (1 point per dollar, double points on beans), works out 18 base points plus 6 bonus points for the beans, and adds 24 points. Her balance goes from 84 to 108, which crosses the 100-point tier. The engine emails her: “You’ve earned a free coffee — show this at the counter next time.” On Friday she’s back, orders her usual, and mentions the free coffee. The barista types her number, sees the reward, taps it, the screen shows “Free coffee — 100 points,” the barista presses Confirm, and 100 points come off. Maria’s balance is now 8, the redemption is logged with the barista’s name and the time, and everyone moves on.

The cost of running this is about $2 a month at small-shop volume. The cost of not running it is the regular who quietly drifts to the cafe across the road because nobody ever made them feel like a regular.

Design rules that shaped every decision

  • Points and money are exact. The earn math and the redeem check are plain Python — no model, no guessing.
  • Four moves, always. Skip, add points, add and announce, hold for review. There is no fifth.
  • Staff confirm every redemption. One tap is fast; the confirm step is what stops a reward going out by mistake.
  • Every points change is logged and reversible. A wrong redemption can be undone in one tap.
  • The rules live in Drive. Changing points-per-dollar or a reward tier doesn’t need a deploy.
  • Emails respect quiet hours and the unsubscribe link. A loyalty email should feel like a treat, not spam.

Why this shape

Most shops run loyalty one of three ways: a paper punch card that customers lose, a spreadsheet nobody opens, or an expensive app with a monthly fee that does ten things you don’t need. The punch card works until the customer leaves it in their other coat. The spreadsheet goes stale the first busy week. And the big app charges you a subscription whether you have 50 members or 5,000.

The setup above keeps the rules somewhere the shop owner already edits — a plain doc — but adds a small system that watches every sale and acts only when there’s a point to add or a reward to announce. Balances are always exact because they live in the system’s own store, not a doc that two people might edit at once. Rewards can’t go out by accident because staff confirm each one. And nothing is ever lost, because every points change is written down and can be undone. The tracker is invisible most of the time; it only speaks up when a customer earns something worth knowing about.

The next four posts walk through each piece in turn: how a shopper joins the program, how a purchase earns points, how a reward gets redeemed, and how a lapsing regular gets nudged back. One diagram per post. A cost breakdown and a final engineering reference at the end.

All posts