Membership points and vouchers: symptom, cause, fix
“My points are missing”, a balance that will not add up, a voucher the till refuses: start from what the member sees. This page is for whoever answers members — the programme owner, a supervisor, support. A membership question is usually not “how do I” but “where did this number go?”, and that needs a chain to walk rather than a row to look up, so read the first section before the tables. Each fix names the applet page that carries the detail.
The fast path for the commonest call, “my points are missing”: stop at the first check that fails (the full chain).
- Open the bill. Is the member on it, and is it the document type and posting status the company’s
MEMBER_POINTconfiguration names? A bill rung up before the card was attached earns nothing, and only a manual adjustment puts those points back. - Do the bill’s lines carry a point amount and a point currency? If not, fix the price set; the document is left unmarked, so a retry awards once the lines are fixed.
- Open the member’s Point Transaction tab. No lines behind a document marked
POSTEDis the broken state: ask BigLedger support for the data-fix run, and never insert lines by hand. - Open the Points Expiry tab. Lots with an end date in the past explain a balance that fell without anybody spending anything, and nothing needs fixing.
- Lines and lots present but the balance zero or stale: ask BigLedger support or your integrator to run the points recalculation, which rebuilds the balance from the lines. It is a route of the points API, and Membership Admin has no button for it; if the balance stays wrong, ask why the queue is not draining.
Walk the chain when a member says their points are missing
“The balance shows zero and they have been shopping here for months.” That one sentence covers five different faults, and they have different fixes — one is unrecoverable, three are, and one is not a fault at all. Work the chain in order and stop at the first link that is broken. Each step has one thing to look at and one answer.
1. Did the sale happen the way points need it to? Open the bill. Is the member on the
document? A bill rung up before the cashier attached the card earns nothing, for ever, and no
retry will fix it — only a manual adjustment will. Is the bill the document type and posting
status the company’s MEMBER_POINT configuration names? With no configuration the backend awards
on INTERNAL_SALES_ORDER at FINAL, so a retailer selling on cash bills earns nothing at all.
Those two plus the configured status are the whole of docTypeValid, and if any fails the
processor returns without a word.
2. Do the bill’s lines carry a point amount? The processor only looks at lines that have both a point amount and a point currency. If no line qualifies it deliberately does not mark the document POSTED, so it can be retried once the rule is fixed — which means a zero here is recoverable and the fix is the price set, not an adjustment.
Check one cause before the obvious ones: the server’s own points pass (which runs only with Auto Apply Points From Pricebook on, and only for lines that arrived with no points) skips any price set whose header filter has no Member Class rule, silently. See Program Design → Put the earning rule on a price set.
3. Are there transaction lines? The member’s Point Transaction tab is the ledger — one row
per points-bearing document line, with the document it came from. Lines present here and a zero
balance on screen means the fault is downstream and the points exist. No lines at all, with a
document whose membership posting status is POSTED, is the one genuinely broken state: the document
says it awarded and nothing did, and its fix is the data-fix run in the next section.
4. Are there lots? The Points Expiry tab shows the control-account lots — one per award, each with its own start date and end date. Its Balance Amount is the lot’s original points, not what is left of it, so a lot the member has partly spent counts in full there; for the remaining points on each lot use the lot query in the membership API (points liability, three figures). Lines with no lots, or lots with an end date in the past, explain a balance that fell without anybody spending anything.
5. Is the stored balance simply behind? The number on the till and in the applet is an accumulator — one stored row per member and point currency — not a live sum. Two different writers maintain it, and knowing which one last touched it is the whole diagnosis:
- On the write path, an incremental writer adds the movement. On an
EXPIRYor an insufficient-balance adjustment it does not subtract — it sets the stored balance to zero. - Immediately afterwards the line is queued to
MEMBERSHIP_CTRL_ACC_AND_CURRENT_BALANCE_UPDATE_PROCESSOR, which recomputes the balance as the sum of every active transaction line for that member and currency and rebuilds the lot.
So the zero is normally momentary and the recompute restores the true figure. When that queue hop is lost, the zero is permanent and it is what the member sees — and that is the difference between the two symptoms worth separating:
| What you see | What it means | What to do |
|---|---|---|
| Balance is stale — right until recently, wrong now | The lines and lots are correct; the accumulator missed a hop | Re-drive the balance: the points recalculation (a support or integrator task through the points API; Membership Admin has no button for it) rebuilds it from the lines |
| Balance is zero with lines and lots present | The incremental writer zeroed it on an expiry or shortfall line and the recompute never arrived | The same re-drive; then check why the queue is not draining |
Balance is zero with no lines, document POSTED | The document was marked as having awarded, and no transaction lines exist behind it | The data-fix run in the next section, never a hand-inserted row |
Balance is zero with no lines and no POSTED flag | Nothing ever awarded. Go back to step 1 | Fix the configuration or the price set; the retry will then award |
The arithmetic that settles it in one line: the sum of a member’s active transaction lines for a point currency must equal their stored balance. The transaction-lines query against the current-balance query. When they differ, the stored figure is the one that is wrong.
Put the points back the right way
There are two ways to restore points that a document should have awarded and did not, and one of them quietly destroys the audit trail.
The right way — re-drive the processing for the document.
A data-fix run, which BigLedger support can trigger for a company, finds every document for that company
that carries a member and has no transaction lines behind it — including ones already flagged
POSTED, which is exactly the broken state in step 3 — and reprocesses each. Void documents are
excluded and never reprocessed. The points arrive with their real source, their real document and
line, and their real validity dates, so the member’s history reads as what happened.
The wrong way — inserting transaction lines by hand. A hand-inserted line has no document behind it, and its per-line balance snapshot is computed against the accumulator as it stood at that moment, so it is not a running total and it is not evidence of anything. A member statement built from those rows has no sale to reconcile against, which means the next dispute has nothing to settle it with.
If neither applies — because the sale genuinely never had a member on it — the answer is a manual
adjustment with a real reason, not a data fix. Whoever holds ALLOW_EDIT_MEMBERSHIP_POINTS makes
it, and it will show up in somebody’s monthly adjustment review
(security and compliance) — which is
correct, because that is what the review is for.
Chase a missing identity number in membership, not in e-invoice
The symptom appears in e-invoice and the cause is in membership, which is why it is usually chased in the wrong place. Correcting a member’s identity number on the membership card does not write it to the customer record: the Details tab’s identity number stays on the card. The member form’s E-Invoice tab writes onto the customer, and the API’s with customer routes run the mapping that copies name, identity number, phone, e-mail and date of birth across. On create the mainstream path does link an entity — creating one with the identity number if there is no match — but where it matches an existing customer by phone or e-mail it leaves that customer’s details as they were.
Fix it on the customer record as well as the membership card, and check both screens show the number before the next invoice. See data management.
Decide which system your counter is allowed to quote
A member’s balance here differs from the one your other loyalty system shows? Nothing in BigLedger reads or reconciles an outside balance, so that is an operating decision rather than a fault: which system the counter quotes, and who reconciles the two on a fixed day, are on Program Design → Decide which system your counter is allowed to quote.
Membership points
| Symptom | Cause | Fix |
|---|---|---|
| Bills for a member earn no points — ever | The company member-point configuration does not name the document type you sell on. With no configuration the backend awards on INTERNAL_SALES_ORDER at FINAL | Set the MEMBER_POINT configuration through the company API to the cash-bill or invoice type and status (Organisation page); there is no screen |
| Member is on the bill, configuration is right, still no points | The bill lines carry no point amount and currency — no price set matched, or the POINT treatment is missing | Check the POS Default Pricebook, the price set’s Doc Hdr rules (Member Class, Branch, absolute Valid Date Range) and Single Line rules; add the POINT treatment (Pricebook). The document is left unmarked so a retry awards once the lines are fixed |
| A price set with a Member Label, Company, Currency or Settlement Method rule applies to everyone | The counter calculator ignores those rule types | Use Member Class, Branch, Entity Type, Customer or Employee Category |
| Multi Line rules award no points | The counter calculator never reads that tab, and the till’s separate purchase-with-purchase pass — which does read it — only discounts; it applies no POINT treatment | Put the item conditions for a point treatment on the Single Line tab |
| Points from Level 1 or higher of a commission scheme never arrive | The points run uses the first treatment only | Put the points logic on Level 0 (Commission Scheme) |
| Points never expire | The lots have no end date (no Validity Period on the treatment, no Valid Date To on the adjustment), or the elimination processor is not scheduled | Date every earning path; schedule MEMBERSHIP_EXPIRY_POINTS_ELIMINATION_PROCESSOR |
| Points expired unexpectedly | The lot’s end date passed and the processor ran | Points Expiry tab; extend Valid Date To on a new adjustment (Membership Admin) |
| After a void, the till still shows the bill’s points, or the redeemed points never came back | A void does not reverse points: the bill’s point lines stay, and only the lots it earned are removed | Post a Point Adjustment on the member; see Points Setup |
| Reward points not applied or points discount missing at POS | Points Discount Item Code not set, member not VERIFIED with POS_ALLOW_VERIFIED_MEMBER_REDEEM_POINTS on, or PTS to CCY rate missing | POS Default Selection; verify the member; PTS to CCY Config (POS General) |
| Point Transaction rows cannot be edited | DISALLOW_EDIT_MEMBERSHIP_POINTS on and the user lacks ALLOW_EDIT_MEMBERSHIP_POINTS | Grant the permission |
OCR receipt is FINAL, no points, Process Status never APPROVED | No enabled subscriber job template; or the template has no priceBookHdrGuid; or the price set has no POINT treatment | OCR Cash Bill troubleshooting table |
Members
| Symptom | Cause | Fix |
|---|---|---|
| New members get random six-digit card numbers | No card-number rule — none of the three Field Settings switches is on, so the form assigns a random number and saves | Field Settings → custom running number (with its starting number), or assign IC / mobile to card number; members already saved keep the number they were given |
| Failed to generate card_no running number | Running-number configuration missing or exhausted | Field Settings → Card Running Number |
| Member search shows only some branches | Branch targets on the read permission | Add the branches |
| Join Date shifted by a day | Timezone | Default Selection → Default Timezone |
An upload ends FAILED and no member was created; or it ends DONE and some members are missing | FAILED: a row has no END DATE, which stops the whole file. DONE with gaps: those rows had no name, neither a mobile number nor an e-mail, or a class or label code that does not exist, and were skipped | Put an end date on every row and create classes and labels first, then upload the missing rows again. A row whose name and mobile number exactly match a live member updates that member |
| Member did not move to GOLD after spending the threshold | There is no automatic upgrade | Change the class on the member form |
Vouchers
| Symptom | Cause | Fix |
|---|---|---|
| Voucher / coupon rejected at POS | No Doc Hdr rule passes; or, for a free gift the till adds by itself, the voucher’s Daily Limit is reached (Exceeded daily coupon redeem limit.). The per-customer limit is not checked at the counter | Voucher Management |
| A ticket redeemed after its redemption period | It was redeemed directly (back office, merchant, storefront), which flips the status without reading the dates; redemption from a finalised document does check them | The direct calls refuse only an already-redeemed ticket, so even an EXPIRED one goes through: check the ticket’s dates before redeeming it directly, or redeem it on a document |
| Add button gone in Ticket Management | ENABLE_MULTIPLE_TICKET off and the voucher is FIXED with a ticket already generated | Turn the setting on |
| Import Tickets file fails | CSV columns do not match the nine expected (voucher code, serial, soft pin, four statuses, code, name) | Download the Sample Format and match it |
| Recurring vouchers never appear | The recurring-voucher run selects no template today, however it is scheduled | Make each period’s voucher by hand or by import in Voucher Management |
| Voucher code cannot be edited | ENABLE_EDIT_VOUCHER_CODE off | Field Settings |
Referral programmes
| Symptom | Cause | Fix |
|---|---|---|
Lineage save through the API fails: …REFERRAL_SOURCE_IS_NULL_OR_EMPTY | The call left out the referral source, which the backend requires (the MLM Admin form now requires it too) | Send a referral source (MLM Admin: troubleshooting) |
| Communication endpoint link never appears | Creating a link from the MLM Admin screen does nothing; through the API, …PRIORITY_IS_NULL_OR_EMPTY means the call left out the priority | Create the link through the API, with a priority |
| Invitations are never sent | MLM_INVITATION_LINK_PROCESSOR is not scheduled; or the program has no ACTIVE endpoint link, or more than one; or the link’s code is not sms, email or whatsapp; or Invite Status was never set; or one unsendable invitation stops each run | Schedule the processor, then work through the five on MLM Admin: troubleshooting |
| Accepted invitation but no lineage | INVITATION_INSERTION_INTO_LINEAGE_PROCESSOR not scheduled, or the child is not yet a participant | Schedule it; enrol the participant |
| QR link gives 404 | The program’s forwarding URL lacks <URL-KEY> or is not a valid URL | Fix the forwarding URL |
…MAX_OR_MIN_LEVEL_IS_BREACHED | Lineage deeper than 10 levels | Flatten the tree |
| Upline commission never paid | The scheme is not type MLM, or the Sales Commission cycle has not run | Commission Scheme; Sales Commission applet |
What is not a fault
- Points that “post with a delay”: the balance is updated by a queue processor after the line is written; the line itself is immediate.
- A class that does not change on its own.
- A points balance that appears in no ledger account.
Related documentation
- Membership in Depth — why each link in the chain can break: the three stages a bill’s points pass through, and the stored balance the till offers.
- Customer and Member — why an identity number on the card does not reach the e-invoice.
- Membership Admin — the member’s Point Transaction and Points Expiry tabs this page reads.
- Registering a Loyalty Member — enrolling a member so the first bill earns.