Program Design Best Practices

A loyalty programme is not a configuration. It is a price you set, a promise you publish and a debt you then carry, and BigLedger holds none of those three — it holds the member, the class, the price set, the point lot and the voucher, and it does what those records say. This page is in two halves: the decisions that are yours, which nobody will prompt you for, and the records that carry them, which behave in ways worth knowing before you commit.

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

A programme is defined by two numbers: what a ringgit of spend earns, and what a point buys back. GadgetSphere awards 1 GSPTS per RM 1 and redeems 100 GSPTS for RM 1. Multiply them and the programme is a 1% discount on every sale, from the day you switch it on, whether or not anybody ever redeems. On RM 40 million of retail turnover that is RM 400,000 a year of gross margin promised away, and it does not appear in any report, any budget or any ledger account in BigLedger — the reports page explains why nothing posts.

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 — because after that row exists, changing it is a change to a published promise rather than a change to a setting. They know they got the number right when, at the end of the first full month, points awarded × the redeem rate, taken from …/membership-points-txn/lines/query filtered to REWARD, comes to the percentage of net sales they wrote down.

Two practical consequences of the same arithmetic:

• A point earned on a discounted line still earns on what the price set says. Decide whether clearance stock, trade-in allowances and gift cards earn at all — and if they should not, keep them out of the item and category rules on the price set, because there is no exclusion list anywhere else.
• Points earn on the line, so whether they earn on tax and freight is decided by which items your rules match. Check it on one real bill at GS-KV-01 before go-live rather than reasoning about it.

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%, and it is the number your accrual is built on (see what you owe your members).

BigLedger gives you the ingredients and not the estimate. …/membership-points-txn/lines/query returns REWARD, REDEEM and EXPIRY lines with dates, so you can take a month’s awards as a cohort and watch what share of it is redeemed over the following year. Finance owns this number, reviews it at each year-end against a full twelve months of lines, and knows the estimate has settled when a cohort’s redemption rate stops moving between reviews.

Two cautions before you trust your first figure. If nobody has scheduled the expiry elimination processor, your EXPIRY count is zero — not because nothing should have expired, but because nothing sweeps (see points expiry). And a low redemption rate is not a saving; it is usually a broken product. Before you book it as breakage, rule out the four causes: points not worth enough to bother with, redemption too awkward at the counter, members never told what they have, or the redemption path not configured at all. The branch managers will know which, and the fastest test is to 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 to these, in the words a member will read:

The loyalty programme owner writes this, whoever approves customer-facing copy signs it, and it is done before the programme is configured rather than after. You know it is good enough when a cashier at GS-KV-01 can answer any row of that table from a card beside the till, without calling head office.

And settle the precedence now, because it will be tested within a month: when your published terms and the screen disagree, the terms are what you owe and the screen is what you built. A member who was promised points on a purchase that earned none gets the points, by manual adjustment, and somebody then fixes the price set.

Decide what one bill may earn, and enforce it yourself

BigLedger has no cap on earning — no upper limit so that a single RM 12,000 laptop sale cannot mint 12,000 points, and no floor so that every bill earns at least something. The price set’s POINT treatment multiplies, and that is all it does.

If your programme needs a ceiling, it is a rule the buyer of the price set enforces, and the place it lives is the item and category rules: exclude the categories whose ticket price would blow the cap rather than trying to cap the points. If you need a genuine per-bill ceiling, the honest answer today is that you cannot have one, and the control is a branch manager reviewing the largest point awards of the week from the point transaction lines (…/membership-points-txn/lines/query, filtered to REWARD and sorted by points) — which is also where a fraud shows up (security and compliance). Do not use the member reward redemption route of the Sales Report for it: that screen loads no points data at all.

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

Points are awarded only when a document’s server type and posting status match the company’s MEMBER_POINT configuration. With no configuration the backend awards on INTERNAL_SALES_ORDER at FINAL — so a retailer who sells on cash bills and never sets this earns nothing at all, and nothing on any screen says so. Set it through the company API to the document type you actually sell on; there is no screen in Membership Admin or Organisation.

It is one document type per company, not a list. A group like GadgetSphere, selling at the counter through GS and online through GSO, sets it once per company.

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

The point amount on a bill line comes from a POINT treatment (price source, operator, value, currency, Validity Period in days) on a price set whose header rules match. A member on a bill whose lines carry no point amounts earns nothing, and the document is deliberately left unmarked so a later retry can pick it up once you fix the rule.

Two calculators read the same price set, and they disagree about one thing. The till works out points in the browser as the line is added, and it needs no Member Class rule. The server runs a second pass when a cash bill or sales invoice with a member is saved — only where Auto Apply Points From Pricebook is on in POS General or Sales Invoice, and only for lines that arrived with no points — and that pass ignores any price set whose header filter has no Member Class rule. So a price set with a Valid Date Range, a Branch rule and a flawless Point treatment earns at the till, and earns nothing on any line the server has to fill in: an invoice keyed without points, a bill whose line the till missed. The only trace is a server log. Add a Member Class rule naming every class you want to earn — including your default class — so both calculators agree, and check it by finalising one bill for a test member before go-live.

The rest of the rule’s shape:

• Use Single Line rules for item conditions. The counter calculator never reads the Multi Line tab, applies Doc Hdr rules as AND, and ignores Company, Member Label, Currency, Settlement Method and OCR Company header rules.
• One price book per consuming applet. POS General, Sales Invoice, Sales Order and Sales Quotation each evaluate only the book named in their Default Selection.
• Only the first treatment on a price-book line is read. Both calculators read the first treatment and go no further, and the backend one skips the price set entirely if that first treatment is not a POINT treatment. A price set whose first treatment sets a price and whose second awards points awards nothing. Put the POINT treatment first, or give points their own price set — and remember that a separate discount price set covering the same item competes with it: the line takes the higher-priority set for its price and its points alike, so it gets one or the other.
• When two point price sets both match, the higher Priority Level wins — and only one applies. Both ends agree on this: the till’s line calculator sorts the matching price sets by priority, highest first, and takes the first whose item rules pass, and the backend point calculator does the same. There is no stacking: a bill line earns from one price set, not from every price set that matched. So a campaign price set that is meant to sit on top of the standing earn rule replaces it rather than adding to it — if you want double points for a fortnight, the campaign price set carries the whole doubled rate, not the extra half. Whoever builds the campaign checks it by finalising one bill during the campaign window and reading the point transaction line, not by reasoning about which rule stacked.
• The Commission Scheme route awards points from Level 0 only, from the first treatment, on a schedule; use it when the rule needs employee category, sales group or document-type conditions a price set cannot express.

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

No processor upgrades or downgrades a class. If GOLD means “RM 5,000 in a year”, a person reads the figures and changes the field. That makes class movement a monthly task with a named owner — usually the branch manager for their own members, or one person at head office for the group — and the way they know it was done is that the count of members in each class moved this month and can be reconciled to the promotions they approved.

• Two or three classes. Each class that matters needs its own price set(s), voucher rules and birthday schedule; the cost of a class is the records behind it.
• Never put tier logic on a label. Labels are for segmentation and newsletter topics, and the rule engines that appear to filter on them do not.
• Tell a member before you demote them, because the product will not. Nothing notifies a member of a class change, so a demotion is discovered at the till by a cashier who cannot explain it.

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

• One currency unless a balance must be shown separately. A second currency is a second balance, a second PTS to CCY rate and a second set of lots — not a different kind of expiry. And the counter’s point-discount screen offers only the first currency in the member’s list (it always takes the first balance), with no way to pick another, so a second currency is a wallet the till cannot reach.
• Every earning path must carry an end date. The POINT treatment’s Validity Period, the commission treatment’s Validity Period (Days), the adjustment form’s Valid Date To, the CSV’s validity columns. A lot without an end date never expires, no matter what your terms say.
• Schedule the expiry run yourself — MEMBERSHIP_EXPIRY_POINTS_ELIMINATION_PROCESSOR in the Scheduler applet. It is not a default clock — registering a processor is not scheduling it. Whoever configures the tenant confirms it by looking for EXPIRY lines on a member whose lot has passed its end date, the day after the first run.
• Do not schedule the “expiry reminder” processor expecting an e-mail. Membership Points Expiry Reminder Processor runs the same expiry as the elimination processor and sends nothing; the one-month reminder e-mail exists only behind an API call. Members hear about expiry from you, or not at all.
• Leave the zero-balance status processor alone unless your points currency is coded ACCESS: the zero-balance membership-status processor reads no other currency.

Decide which redemption button your programme was priced for

Redemption at the counter is either a settlement line or a discount line, and the two convert differently: the member-points settlement panel uses the rate you configured, and the separate Add Point Discount screen converts at a hard-coded 100 points to RM 1. Conversion rates has the detail and the file lines. Decide which one your cashiers use, configure it, and say so in the counter’s own instructions — because the member gets a different answer depending on which button is pressed and nothing on either screen warns them.

Set the voucher limits explicitly, and give the promotion an owner

• Choose the type by what it sits on. SETTLEMENT redeems on a settlement line; PRODUCT on a product line; DISCOUNT changes the amount by its treatment; REWARDS adds points.
• Set Voucher Limit Per Customer and Daily Limit explicitly — the defaults are 1 and 0 (unlimited), and an unlimited daily limit is how a promotion becomes expensive overnight.
• Give every ticket its redeemable dates, and expire them when the campaign ends. The counter’s voucher payment and the redemption step at FINAL both test a ticket’s own redeemable-from and redeemable-to dates; nothing moves the ticket to EXPIRED on its own, though — that takes the expiry-checking call, and nothing runs it on a schedule — so until it runs a ticket past its date still reads VALID in every listing. Whoever runs the promotion runs the expiry check the morning after it ends and confirms the tickets went EXPIRED.
• Recurring vouchers: one run a day. The creation processor duplicates vouchers if it runs more often.
• Birthday gifts are a schedule you create, per class, as points (with a validity in months — twelve if you leave it empty) or as vouchers.

Decide now what you will owe when something changes

Three changes will happen and the product has no concept of any of them, so the answer has to be a decision somebody already made:

• A rate change. Every point already earned was earned against the old promise. Decide whether you honour the old rate for existing balances — which means announcing a cut-off date and letting members spend first — or apply the new rate to everything. Either is defensible; discovering you have no position when a member complains is not. The programme owner decides, before the change is made, and the notice period goes in the terms.
• A branch or a company closes. A member’s balance has no company and no branch on it at all, so nothing changes in the data when GS-PEN-01 shuts — the member simply has nowhere local to spend. Decide whether they are directed to another branch, paid out, or given a voucher, and tell them before the doors close rather than after.
• The programme ends. There is no wind-down anywhere in the product. What is owed is the outstanding balance at your redeem rate, and settling it is a commercial decision plus a manual journal. Finance produces the number from …/current-balance/query on the day of the announcement, and that figure is the ceiling on what the wind-down can cost.

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

Automatic tier progression, qualification windows, grace periods, anniversary rewards, a rewards catalogue, partner or charity redemption, a per-bill earning cap, a points liability posting — the product has none of them, and a programme brief that assumes them will fail at configuration time. Each one is somebody’s job instead:

Related

• What you owe your members — pricing the promise as an accrual, and releasing it.
• Security and compliance — how points are stolen and what catches each.
• Points expiry — the lot model and the sweep.