Services

How to Build a Loyalty Points System: Ledger Design, Refund Clawbacks and Points Liability

2026.09.01 · 45 views
How to Build a Loyalty Points System: Ledger Design, Refund Clawbacks and Points Liability

Decide what one point costs before you write a line of code — and never store free points and paid stored-value points in the same table

Share:

A bubble tea brand with three stores came to us carrying one spreadsheet: 4.8 million points issued over two years, 620,000 redeemed, and 4.18 million sitting in a file a store manager maintained by hand. They assumed digitising a paper card was a two-week job. Week one produced three complaint types instead — points not clawed back after refunds, one phone bound to two member accounts, and points earned at store A rejected at store B. The hard part of a loyalty programme is never the collecting. It is the correctness of the ledger after the points leave your hands.

Where This Fits, and Where It Does Not

Points work best for short repurchase cycles, low ticket sizes and multiple channels. For a business a customer uses once in a lifetime, they do close to nothing.

Good fit:

  • Retail, food and beverage, salons and pet supplies with a repurchase cycle under 30 days
  • Three or more stores, or an online plus in-store setup needing one shared balance
  • More than 800 transactions a month, where manual tallying already produces errors
  • Businesses wanting to convert an anonymous LINE friend list into identified members
  • Businesses already discounting, who want to reward repurchase instead of discounting everyone

Poor fit:

  • High-ticket, once-in-a-lifetime industries such as wedding photography, interior fit-out or study-abroad agencies — referral bounties beat points
  • Under 300 transactions a month: the pool is too small to detect behaviour change
  • Gross margin below 15%: point cost eats the profit directly; sell add-ons instead
  • No POS or order system yet: with no transaction source, points cannot be issued
  • One-off sales pushes — a single-use coupon code is cheaper than a system

Alternatives Matrix: Four Roads and Their Real Cost

OptionSetupAnnualStrengthHard limit
Paper stamp card~NT$3,000 printingUnder NT$5,000Zero learning curve, high acceptanceNo list, no behavioural data, forged cards and favour stamps are unauditable
Built-in LINE OA stamp card0NT$800–1,200/month and upLive the same day, sits on your friend listNo cross-campaign accumulation, no POS integration, data cannot be exported for analysis
E-commerce or POS platform points0–NT$20,000NT$3,000–15,000/month rentNatively tied to orders, automatic refund clawbackRules limited to the platform template; balances do not carry across web and store
Custom service (Laravel)NT$150,000–450,00015–20% of build costFull control of rules, channels and data; connects any POS or storefrontHigh upfront cost; starting to code before the rulebook is final guarantees rework

The decision rule is short: one channel, use the built-in feature; two or more channels sharing one balance, build it. The middle ground — wanting cross-channel without paying for it — usually ends up paying twice.

The Full Process: 8 to 10 Weeks

  • Stage 1 | Rulebook (weeks 1–2): define earning events, point denomination, expiry policy, redemption catalogue, refund clawback rules and manual-adjustment permissions. Deliverables are a Notion rulebook and a Google Sheets cost model with three issuance scenarios. Skip this and everything downstream gets rewritten.
  • Stage 2 | Data model and flows (weeks 2–3): draw binding, earning, redemption and refund flows in Figma; define the ledger schema in dbdiagram.io. Deliverables are a reviewable ERD and state-machine diagram.
  • Stage 3 | Points backend (weeks 3–6): build an immutable ledger in Laravel — one row per movement, balance derived from the ledger — and wrap every deduction in a transaction using Laravel pessimistic locking (lockForUpdate) so two registers cannot spend the same balance. Deliverables: API docs and a load-test report.
  • Stage 4 | Front end and admin (weeks 5–8): member statement and redemption pages with LINE Login binding, plus a Filament admin for rule configuration and manual-adjustment audit. For in-store redemption, a Flutter app issuing single-use QR tokens valid for 30 seconds.
  • Stage 5 | Reconciliation and pilot (weeks 8–10): run one store for two weeks, comparing POS transaction count against points-issued count daily. Roll out only when the gap is zero.

Real Cost Breakdown

Ranges from actual ScriptWalker projects (estimates; they move with rule complexity):

ItemNT$
Rulebook and cost model (3–5 person-days)18,000–30,000
Points ledger backend (earn, spend, hold, claw back)60,000–110,000
Member front end (statement, redemption, binding)35,000–60,000
Filament admin and audit reports40,000–70,000
In-store redemption app (Flutter, optional)60,000–120,000

Hidden costs people forget:

Three budget tiers:

  • Entry, from NT$150,000: single-channel earn and redeem, LINE binding, manual admin adjustments. Enough for one or two stores to validate the rules.
  • Standard, from NT$280,000: adds in-store QR redemption, POS integration, automatic refund clawback and audit reporting. Most 3–10 store clients land here.
  • Advanced, from NT$450,000: adds paid point top-ups with payment and e-invoicing, per-store settlement, member tiers and automated marketing triggers.

Reality vs Expectation

Clients assumeWhat actually happens
It is just digitising a paper card, two weeksThe rulebook alone takes 1–2 weeks; code written before rules are frozen is code written twice
The main work is the earning featureRoughly 80% of hours go to refund clawback, cross-store merging and daily reconciliation
Be generous with points so customers engageOnce issuance cost passes 3% of revenue margin turns red, and shrinking points later always triggers complaints
LINE binding is simple, just scan a codeMultiple accounts per person, phone changes and duplicate bindings generate the largest support ticket volume after launch
Redemption just subtracts from the amount dueHow you apply the discount affects recorded sales and invoice amounts; ask your accountant before development starts

Six Traps and How to Avoid Them

  • Incrementing a members.balance column directly: errors become untraceable. Use an immutable ledger — one row per movement, balance summed and cached.
  • Two registers spending the same balance: you go negative. Wrap deductions in a database transaction with a pessimistic lock.
  • No clawback on refunds: attach point events to the order state machine so refunds reverse automatically; record a negative balance rather than silently skipping.
  • Free points and purchased points in one table: they differ legally. Separate ledgers, reports and expiry policies.
  • No audit trail on manual adjustments: force a reason and an operator on every manual grant, and enable Filament activity logging. When a staffing dispute arrives, that log is the only evidence.
  • Replayable redemption QR codes: use single-use tokens valid for 30 seconds and voided on redemption. Forwarded screenshots are the most common in-store abuse.

Success Metrics and the 90-Day Roadmap

  • Day 30 — technical: point issuance success rate at or above 99.5%, zero variance between POS transaction count and issuance count, member binding rate (bound members divided by transactions) reaching 25%. Revenue is not the topic yet.
  • Day 60 — behavioural: first-redemption rate (members redeeming at least once within 60 days of earning) targeting 20% or more. Start tracking points liability; above 5% of revenue, cut the issuance rate.
  • Day 90 — commercial: compare repurchase interval and average ticket between members and non-members; A/B test the redemption catalogue and replace the worst-performing item; sweep dormant points and send one reminder 14 days before expiry.

Decision Checklist: 12 Yes-or-No Questions

  • ☐ My customers repurchase within 30 days on average
  • ☐ I process more than 800 transactions a month
  • ☐ My gross margin is above 15% and can absorb 1–3% point cost
  • ☐ I have two or more channels needing one shared balance
  • ☐ I already have a POS or order system supplying transaction data
  • ☐ I can state exactly what one point is worth in currency
  • ☐ I have set a ceiling for issuance cost as a percentage of revenue
  • ☐ I know how points should behave on a refund
  • ☐ I intend to let members buy points or top up with cash
  • ☐ Someone can spend 10 minutes a day reviewing reconciliation gaps
  • ☐ I am willing to book unredeemed points as a liability
  • ☐ I accept a two-week single-store pilot for version one

Eight or more: start building. Five to seven: run a platform built-in for three months first. Under five: fix the POS and the rules before discussing a system.

FAQ

Do free points fall under Taiwan gift certificate regulations?

Under the preamble to the Ministry of Economic Affairs Mandatory and Prohibited Provisions for Gift Certificate Standard Contracts, the rules exclude vouchers and discount coupons issued by the issuer free of charge — so pure loyalty rewards generally sit outside scope. The moment a customer pays cash for points or tops up, however, the instrument resembles a paid gift certificate, which carries a performance guarantee of at least one year and may not carry a stated expiry. Keep the two point types structurally separate and have a lawyer or accountant confirm your design before launch.

What should one point be worth?

Set the cost ceiling first and derive the denomination. Point cost ratio equals value issued in a period divided by revenue in that period. For retail and food service, 1–3% is the safe band; above 5% margin compression is near certain. If you pick 2% with an average ticket of NT$150 and one point per NT$1 spent, the cost of goods behind a 100-point redemption cannot exceed NT$3.

Can I start on SaaS and migrate to a custom build later?

Yes, but check the export format before you sign. Ask whether you can export every individual point movement, not just current balances. With balances alone, all historical behaviour analysis resets after migration and refund clawbacks stop reconciling.

Can points have an expiry date?

Free points usually can, provided the member terms state it clearly, expiry runs first-in-first-out by batch, and a reminder goes out beforehand. In practice 12 months beats 6 — too short and low-frequency customers simply give up. Points acquired for payment need separate legal assessment.

Do I need a mobile app?

Usually not on the member side; LINE Login plus a web page is enough, and few people install an app just to collect points. The genuine native use case is in-store redemption — when you need a camera, offline buffering and fast scanning, a Flutter staff app is far more stable than staff operating a browser.

Next Step

ScriptWalker's Membership Points and Loyalty System build starts at NT$150,000, covering the rulebook, points ledger, member front end and admin audit trail. We also offer a free 30-minute rules diagnostic: bring your monthly transaction count, gross margin and current discounting, and we will calculate your point cost ratio and a recommended denomination on the call — usable even if you end up choosing a platform built-in.

Share: