Program Design Best Practices

“How much will this loyalty programme cost us, and who keeps it honest once it is running?” Nothing in BigLedger asks that question for you, so answer it before anyone sets up a member. This page is for whoever owns the programme — usually marketing, with finance and whoever runs the tills beside them. By the end you will have priced the two rates, written the terms members will read, built the earning rule so it does what those terms say, and set up a monthly check that tells you the programme is still the one you approved. The decisions take an afternoon; the check takes half an hour a month.

A loyalty programme is a price you set, a promise you publish and a debt you then carry. BigLedger holds the member, the class, the price set, the point lot and the voucher, and does what those records say. The price, the promise and the debt stay with you.

Meet the programme this page designs

GadgetSphere Sdn Bhd runs one programme, GSPTS, for walk-in members at its 22 branches (company GS) and for shoppers on its web store (GSO); the wholesale company, GSD, has no members. The brief: 1 GSPTS per RM 1 spent, 100 GSPTS takes RM 1 off a bill, points live twelve months, three classes — STANDARD, SILVER and GOLD — Silver earns 1.5 points per ringgit and Gold earns double.

That shape is the common one. Across the groups we can see, points earned on bills and spent at the till are by far the commonest reward, vouchers are much rarer, and where a company has set which document awards points it is almost always the cash bill.

One situation runs through the page: a Gold member buys a RM 6,000 laptop at GS-KV-01 during a double-points fortnight. How many points they earn, what those points cost, whether the campaign changed anything and when the points die are each decided by a different record, and each section below says who decides it, when, and how they know it held.

Work out what your two rates cost you, before you publish either

Multiply GadgetSphere’s two rates — 1 point per RM 1 earned, 100 points per RM 1 back — and the programme is a 1% discount on every Standard member’s sale, from the day you switch it on, whether or not anybody redeems. Silver at 1.5 points is 1.5%; Gold at double earn is 2%. On RM 40 million of member turnover that is RM 400,000 to RM 800,000 a year of margin promised away, and it appears in no report, budget or ledger account: the point documents post nothing (what you owe your members).

Nobody in the product does this arithmetic and no screen asks you for it. The person who signs off gross margin does it, on paper, before the PTS to CCY Config row exists — once the row exists, changing it is a change to a published promise, not to a setting. Two facts decide the base:

Points are worked out on what the member paid for the line — after its own discount, tax included. The till and the server’s fill-in pass both multiply the line’s transaction amount. Work your percentage out on that, not on net sales.
The points are fixed when the line is added, and stored on it. Changing the price set later recalculates no bill already rung, so the first month’s awards are a fair test of the rate as it was.

How you know you got it right: at the end of the first full month, take that month’s REWARD lines (…/membership-points-txn/lines/query), multiply by the redeem rate and divide by the member bills’ total. It should match the percentage you wrote down. Higher usually means a campaign price set still inside its dates.

Estimate what you will never pay out, and put a date in the diary to revisit it

Some of what you award will never be spent. That share — breakage — is the difference between a programme that costs 1% and one that costs 0.3%. Finance owns the estimate: take a month’s awards as a cohort from the point transaction lines and watch what share is redeemed over the following year; review it each year-end, and treat it as settled when a cohort’s redemption rate stops moving between reviews. Whether it reaches the accounts as deferred revenue or a provision is a judgement for whoever signs them, set out with both options on What You Owe Your Members.

Two cautions before you trust the first figure. With no expiry clock running, your EXPIRY count is zero because nothing swept, not because nothing lapsed — and across the groups we can see, an active expiry clock is rare. And a low redemption rate is usually a broken programme, not a saving: points worth too little, redemption too awkward at the counter, members never told their balance, or the redemption path never configured. Ask three cashiers at three branches how a member redeems.

Write the terms you will show members, before you configure anything

None of this is in any system, and it is the actual product. Before the first card is issued, write down and get approved the answers below, in the words a member will read. The right-hand column is what BigLedger does about each one, which is often less than the member assumes.

The member asks	What your terms must say	What BigLedger does about it
How do I earn?	The rate, and what does not earn	A price set with a POINT treatment, matched by item and category rules — or, for single items, the item’s own pricing-scheme entry
What is a point worth?	The redeem rate, in ringgit	PTS to CCY Config — but read conversion rates first: the counter has two redemption buttons and they do not agree
When do my points die?	The validity, and the notice you will give	Each lot carries its own end date and expires only when a scheduled run sweeps it. No reminder goes out on a schedule — the processor named for reminders expires points instead — so the notice is yours
Does my membership expire?	Whether a card lapses, and what happens to its points	The till works out no points for a member whose card end date has passed, and its redemption screens take none
What if I return something?	Whether the points come back	A void does not change the balance the till shows and does not give back points spent on the bill. Test one return at `GS-KV-01` before you print this term; the dependable correction is a Point Adjustment on the member
What if I lose my card?	Whether the balance follows the person	The balance belongs to the member record, not to a plastic card; whoever answers member queries finds the record and carries on
Can you change the rules?	The notice you will give, and what happens to points already earned	A rate change takes effect at once and tells nobody

The programme owner writes this, whoever approves customer-facing copy signs it, and it is done before configuration. It is good enough when a cashier at GS-KV-01 can answer any row from a card beside the till without calling head office.

When your terms and the screen disagree

The terms are what you owe; the screen is what you built. A member promised points on a purchase that earned none gets them by Point Adjustment, and whoever owns the price set fixes the rule the same day, so the next member does not need the same adjustment.

Decide whether a membership itself expires

Members created at the till can be given a card end date by default, and the member import carries one too. A card past its end date stops earning and redeeming at the till, and nothing tells the member. Across the groups we can see, active members whose card end date has already passed are common. If your terms say membership does not expire, the programme owner checks that the till’s default and the import agree, and clears a past end date on anyone who should still be earning.

Decide what one bill may earn, and enforce it yourself

At 2 points per ringgit the Gold member’s RM 6,000 laptop earns 12,000 GSPTS wherever a points set, not the 5% Gold price, wins that line — RM 120 of future merchandise from one line. BigLedger has no cap on earning: a line earns whatever its rule multiplies to. Whoever designs the earning rule decides whether that is acceptable, and the cap lives in the rule’s shape:

Give high-ticket categories a fixed award. A POINT treatment with the ABSOLUTE operator awards a fixed number per bill line whatever the price; a laptop price set at ABSOLUTE 3,000 caps every laptop line at RM 30 of give-back. It is per line, not per unit: two laptops on one line earn 3,000.
Or keep the category out of the earning rule — the exclusion most groups use. For a single item there is a second: switch on Enable Points Reward at 0 points on the item’s pricing-scheme entry, and at the till that item earns nothing from any price set on lines priced on that scheme (Pricing Scheme Rewards).

A ceiling across a whole bill is not available. The control that replaces it is a person: each week a branch manager reads the largest REWARD lines, sorted by points, and confirms each is a sale they would have approved — which is also where points fraud first shows (security and compliance). The member reward redemption route of the Sales Report loads no points data, so it will not serve.

Set the company member-point configuration first, or your cash bills earn nothing

Points reach a member only when a document’s type and posting status match the company’s member-point configuration. With no configuration the backend awards on the sales order at FINAL, so a retailer selling on cash bills earns nothing at all while the till shows points on every line. Your BigLedger contact sets it through the company API; there is no screen in Membership Admin or Organisation. It is one document type per company, so GS and GSO each need their own. Whoever runs the tills asks for it as soon as they know which document each company sells on, and confirms it on the first member bill.

The same setting decides when points are taken off. On a company whose configuration names a different document, a redemption at the till is accepted at FINAL and never deducted from the balance — a known issue, reported to engineering. Set it before any member spends a point, and before you load opening balances.

Put the earning rule on a price set — and give the price set a Member Class rule

The record that gives Gold members their price also gives them their points, so one price book serves both and a campaign is one more price set. The cost of that design is that price and points compete: a bill line takes one price set — the highest-priority one whose rules match — for its price and its points alike. Whoever maintains the price book builds the rule from the programme owner’s written rates (price book configuration has the screens); four things decide whether it does what the terms say.

A Member Class rule naming every class that earns, default class included. The till works points out without one, but the server’s fill-in pass — which, where Auto Apply Points From Pricebook is on, fills cash-bill and invoice lines that arrived without points — drops a price set with no Member Class rule. The member earns at the till and nothing on an invoice, and only a server log records it.
The POINT treatment first on the line. Only the first treatment is read, and the server skips the set if that treatment is not POINT.
Campaigns that replace, not add. For the double-points fortnight the campaign set carries the whole rate and a higher Priority Level. If it is ×2 for every class, it outranks Gold’s own ×2 set and our Gold member earns ×2 — the same as any other day — while a Silver member gains half a point per ringgit. For ×4, the campaign needs its own Gold set ranked higher still. The ADD operator gives the line amount plus a fixed number, which at 1 point per ringgit is “standard points plus 200 bonus per line” in one rule.
Items that carry their own points. An item’s entry in the till’s pricing scheme can award its own points, and when it does, the price set’s points — campaign included — are ignored for that item. The same entry can price an item in points, with an optional cash top-up: the nearest thing to a rewards catalogue at the counter, which a few groups use.

How the builder knows it held: during the campaign window, finalise one bill per class for a test member and read the REWARD line on the member’s Point Transaction tab — not the points on the till screen, which are the till’s own working.

Move members between classes yourself, and put the review in somebody’s diary

No processor upgrades or downgrades a class. A class is set by the member form, by import or as the default at creation; nothing reads spend, points or visits to change it. If SILVER means “RM 2,000 in a year” and GOLD “RM 5,000”, a person reads the figures and changes the field — monthly, with a named owner (the branch manager for their own members, or one person at head office). They know it was done when the count in each class moved by exactly the promotions they approved.

Keep the ladder short. GadgetSphere stops at three. Each class needs its own price set, voucher rules and birthday schedule; the cost of a class is the records behind it.
Keep tiers off labels. The till and the sales-document price calculators treat a Member Label price rule as met by everybody, so a tier built on a label prices every member as that tier.
Tell a member before you demote them. BigLedger sends the member nothing, so a demotion is otherwise discovered at the till. A member saved from the form, the API or an import raises the MEMBERSHIP_CARD_UPDATED webhook event, class included, which your developers can turn into the notice.

Date every point you award, then confirm the sweep actually ran

Every earning path carries an end date — the POINT treatment’s Validity Period, the commission treatment’s validity, the adjustment’s Valid Date To, the import’s validity columns. A point written without one is given an end date in the year 9000, and web-store points one in 9999: in practice they never expire, whatever your terms say.
Schedule the expiry run — MEMBERSHIP_EXPIRY_POINTS_ELIMINATION_PROCESSOR, as an ACTIVE row in the Scheduler. It is not a default clock. Until it runs the till goes on offering lapsed points, because its balance is a stored running total, not recalculated from the lots at the moment of sale. Whoever administers the tenant creates it at go-live and looks for EXPIRY lines the day after the first run. Switched on late, the first run releases every lapsed lot at once — warn finance first.
Do not schedule the “expiry reminder” processor for an e-mail. It runs the same expiry and sends nothing.
One points currency unless a balance must be shown apart: the counter’s point-discount screen takes only the member’s first balance, so a second currency is a wallet the till cannot reach.

Decide which redemption button your programme was priced for

The member-points settlement converts at the rate you configured; Add Point Discount converts at a fixed 100 points to RM 1 (conversion rates). At GadgetSphere’s rate they agree; at any other they do not, and neither screen warns the member. Whoever runs the tills picks one and writes it into the counter instructions.

Cap a voucher promotion by the tickets you make, not by its limit fields

Do not lean on Voucher Limit Per Customer or Daily Limit. The first limits how many tickets a signed-in customer can claim from your web store’s voucher list; the second is read only when the till adds a promotion’s free gift by itself. Neither is checked when a cashier redeems a ticket or the bill is finalised. The promotion’s owner caps it by the tickets generated (a FIXED quantity) and checks redemptions against that count each morning of the campaign.
Expire tickets the morning after the campaign. The counter and the redemption step at FINAL test a ticket’s own dates, but nothing moves a ticket to EXPIRED on a schedule, so a lapsed ticket reads VALID in every listing until someone runs the expiry check.
Make each period’s recurring voucher by hand for now. The scheduled creation run selects no template a person would build, so it creates nothing.
Pair a birthday schedule with its clock. The gift run keeps no record of who it gifted, so a monthly gift on a daily clock gives again every day of the month.

Decide now what you will owe when something changes

None of these is a concept in the product, so the answer has to be a decision somebody already made:

A rate change. Changing the PTS to CCY row revalues every outstanding point overnight, at the till and in finance’s figure. Honour the old rate for existing balances (announce a cut-off and let members spend first), or apply the new one to everything. The programme owner decides before the change, and the notice period goes in the terms (Conversion Rates → What you owe members if you change it later).
A branch or a company closes. A balance carries no company and no branch, so nothing changes in the data when GS-PEN-01 shuts — the member just has nowhere local to spend. Decide between another branch, a payout or a voucher, and tell them before the doors close.
The programme ends. What is owed is the outstanding balance at your redeem rate; settling it is a commercial decision plus a manual journal. Finance takes the figure from …/current-balance/query on the day of the announcement — the ceiling on what the wind-down can cost.

Decide which system your counter is allowed to quote

A business running loyalty in BigLedger alongside another system has two balances and no reconciliation between them — nothing in the membership module reads, writes or compares an outside balance, and there is no import beyond the point-transaction CSV. That is a permanent operating condition, not a migration stage, so it needs an answer rather than a plan.

Decide which system the counter is allowed to quote, say it in the counter instructions, and give one person the job of reconciling the two on a fixed day. The instrument on our side is …/membership-points-txn/lines/query, which gives every movement with its date, and the document it came from where it has one; the other side has its own. They know the reconciliation is honest when a member picked at random gets the same answer from both, and the two systems’ movements for the month agree.

What the product will not decide for you, and who does it instead

Automatic tier progression, qualification windows, grace periods, anniversary rewards, a back-office rewards catalogue, partner or charity redemption, a per-bill earning cap and a points liability posting are not in the product, and a brief that assumes them fails at configuration time. Each is somebody’s job instead:

Not in the product	Who does it	When	How they know it worked
Tier progression	The branch manager or head office, on the member form	Monthly, in the diary	The class counts moved by exactly the promotions approved
Qualification windows and grace periods	The same person, reading the point transaction lines before they promote or demote	At the same monthly review	No member was demoted who had spent inside the window
A rewards catalogue	Whoever runs promotions, as vouchers with a fixed ticket count; points-priced items through the pricing scheme at the till, and points-for-vouchers on a web store	Before the campaign	Tickets generated equals tickets you meant to issue
A per-bill earning cap	Whoever builds the price sets, with fixed awards on high-ticket categories; a branch manager reviews the largest awards	At price-set design, then weekly	The largest weekly `REWARD` line is one you would have approved
A points liability	Finance, by manual journal	Each month-end before the period locks	The accrual ties out

How you know the programme is still the one you approved

Half an hour on the first working day of the month, for the programme owner and finance together:

The give-back rate. Last month’s REWARD lines × the redeem rate ÷ member bills’ total matches the rate you approved, or differs by an amount you can name the cause of. The lines are written by a job after each bill’s FINAL, carrying the points as worked out at the sale — a stored record, not a recalculation from today’s rules.
The three figures agree — the lines, the stored balances the till offers and the unspent lots. What You Owe Your Members names the reasons they differ and which way each moves.
The sweep ran: an EXPIRY line is dated last month, if any lot ended in it.
The classes moved by the promotions approved, and no member your terms keep active has a past card end date.
The largest awards were reviewed at every branch.

When it goes wrong

What you see	Usual cause	What to do
The till shows points; the member’s Point Transaction tab has nothing	The company’s member-point configuration names another document	Ask your BigLedger contact to set it for that company; finalise one test bill
Members spend points and their balance does not drop	The same configuration — a known issue, reported to engineering	Set the configuration; take the spent points off by negative Point Adjustment
The double-points campaign earned no more than usual	A lower Priority Level than the standing set, a set carrying only the extra half, or items whose pricing-scheme entry awards its own points	Re-rank; give the campaign the whole rate; check the item’s pricing-scheme entry
A member earns at the till and nothing on an invoice	The price set has no Member Class rule	Add one naming every class that earns
A long-standing member suddenly earns nothing at the till	Their card end date has passed	Decide what your terms say; clear or extend the date
Lapsed points are still spendable, and the liability keeps growing	No `ACTIVE` expiry clock, or lots dated 9000 or 9999	Create the clock; date every earning path
Every member born this month got the birthday gift again today	A monthly gift on a daily clock	Match the clock to the gift; reverse the extras by Point Adjustment
A voucher promotion redeemed far more tickets than planned	The limit fields were relied on	Cap by tickets generated; expire the rest
The same points are worth different amounts on two bills	Cashiers used both redemption buttons	Pick one; put it in the counter instructions

A member who says their points are missing gets the walk-the-chain procedure before anybody adjusts anything.

How this fits with the rest of membership

What must exist first: the company’s member-point configuration, a points currency and its rate, member classes, a price set with a POINT treatment and a Member Class rule, a terminal whose default price book names it, and an ACTIVE expiry clock. Setting Up the Programme puts them in order and names who sets each.

What becomes possible: the same classes target vouchers and choose who gets the birthday gift, so one set of tiers serves pricing, points and promotions (rewards setup); and a programme with written terms and a monthly check is one finance can carry with confidence.

Which tool, when: a price set for points a whole tier earns on every bill; the item’s pricing-scheme entry for one item’s own points or points price; a commission scheme for rules a price set cannot express, awarded in a scheduled run; a voucher for a promotion with a fixed count, or for one member.

What breaks elsewhere: a rate change revalues every outstanding point at the till and in finance’s figure at once; repointing the member-point configuration also changes which documents the commission scheme’s points run reads; a promotion price book set as a terminal’s default stops tier prices and tier points together.

What it is used alongside: a customer record. The e-invoice and a birthday voucher follow the customer, not the card (the member who is not the customer).