loyalty-program
Model the economics of a points-based loyalty program before you launch it. Feed in average ticket, visits per month, points per dollar, and reward size to get program cost per member, effective rebate rate, breakage-adjusted cost, and ROI versus the no-program baseline. Use when deciding whether a punch-card or points program will pay for itself.
$ skillbank install loyalty-program@1.0.0 # pins exactly 1.0.0 · README + changelog included
Loyalty Program
Overview
Loyalty programs feel free to run and aren't. math.py turns your program idea into numbers: how fast members earn a reward, what each reward really costs you after breakage (points that never get redeemed), your effective rebate rate as a percent of spend, and — the part that matters — whether the extra visits the program drives pay for it compared to doing nothing.
Every number is per member per month, so you can scale it to any member count. The verdict line tells you plainly whether the program pays for itself at your assumed visit lift.
All data stays local — nothing is uploaded anywhere.
Installation
1. Copy the loyalty-program/ directory anywhere convenient. 2. Make the script executable (Unix):
chmod +x scripts/math.py
No pip install needed — standard library only.
Configuration
No config files. All inputs are command-line flags (see Inputs). The three that need honest estimates:
--breakage(default0.25): fraction of points never redeemed. 20–30%--visit-lift(default0.15): how much more often members visit because--margin(default0.60): your gross margin as a fraction.
is typical for small-business programs.
of the program. Be conservative — 10–15% is a defensible guess.
Inputs
| Flag | Required | Description | |---|---|---| | --avg-ticket | yes | Average spend per visit, dollars | | --visits-per-month | yes | Average visits per member per month | | --points-per-dollar | yes | Points earned per dollar spent | | --reward-dollars | yes | Dollar value of one reward (e.g. 10 = $10 off) | | --reward-points | yes | Points needed to earn one reward (e.g. 100) | | --breakage | no | Fraction of points never redeemed, 0–1 (default 0.25) | | --visit-lift | no | Assumed fractional visit increase (default 0.15) | | --margin | no | Gross margin as a fraction, 0–1 (default 0.60) |
Exit codes: 0 = ok, 2 = bad/missing input.
Worked example
A coffee shop: $42 average ticket, members visit 2.5×/month, earn 1 point per dollar, and get $10 off per 100 points.
$ ./scripts/math.py --avg-ticket 42 --visits-per-month 2.5 \
--points-per-dollar 1 --reward-dollars 10 --reward-points 100
Loyalty program economics (per member)
====================================================
Points earned per visit: 42.0
Points earned per month: 105.0
Months to earn one reward: 0.95
Reward accrual rate: 1.05 rewards/month
Spend required per reward: $100.00
Cost per reward (after 25% breakage): $7.50
Effective rebate rate: 7.50% of spend
Program cost per member/month: $7.88
vs. no-program baseline (per member / month)
----------------------------------------------------
Baseline spend: $105.00
Spend with program (15% visit lift): $120.75
Incremental revenue: $15.75
Incremental gross (60% margin): $9.45
Net monthly benefit: $1.57
ROI on program cost: +20.0%
Break-even visit lift: 12.5%
Verdict: program pays for itself at the assumed lift.
Reading it: the program costs $7.88/member/month and needs at least a 12.5% visit lift to break even. At the assumed 15% lift it nets $1.57/member/month. If your real lift is under 12.5%, raise the points threshold or shrink the reward and re-run.
See references/program-design-notes.md for guidance on picking the earn rate and reward size.
Version history
Changelog
1.0.0 — 2026-09-27
- Initial release:
scripts/math.pymodels loyalty-program economics per member — points accrual, months to reward, breakage-adjusted reward cost, effective rebate rate, cost per member/month, and ROI vs. the no-program baseline including break-even visit lift. Includesreferences/program-design-notes.md.