Membership points and vouchers: symptom, cause, fix
Start from the symptom. Each fix names the applet page that carries the detail. Read the first section before the tables: 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.
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 backend point calculator skips any price set whose header filter has no Member Class rule, silently. See program design.
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, end date and remaining balance. 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 recalculation queue in Membership Admin 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: editing a member never touches the customer, and only 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 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 source; 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.
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 |
| Upload rejected on the Checking tab | Class or label code not found, date format, missing mandatory column | Fix the row; create classes and labels first |
| 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 | Per-customer or daily limit reached, or the voucher has no rule header | 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 row will not save: …REFERRAL_SOURCE_IS_NULL_OR_EMPTY | The backend requires a referral source though the form marks it optional | Pick one (MLM Admin) |
Communication endpoint link will not save: …PRIORITY_IS_NULL_OR_EMPTY | Priority is required server-side | Enter a priority |
| Invitations are never sent | The program has no communication endpoint link, or MLM_INVITATION_LINK_PROCESSOR is not scheduled | Link a Unified Contact Center endpoint; schedule the processor |
| 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.