Skip to content

Retail Loyalty Program

GadgetSphere wants every walk-in customer at its 22 branches to be a member who earns one GSPTS per ringgit and can spend points at the till. This page follows one customer through that loop and names the applet at each step. It is the shape most of the other use cases build on.

Before the first bill

What must existWhereWhy
A point currency GSPTS and a points-to-money rate (say 100 points = RM 1)Membership Admin → PTS CCY Module and PTS to CCY ConfigWithout a currency nothing is earned; without a rate nothing can be redeemed for money
A card-number rule (running number, IC or mobile)Membership Admin → Settings → Field SettingsA member cannot be saved without a card number source
Member classes STANDARD and GOLDMembership Admin → Member ClassOptional, but the price-book rule below needs them
The company member-point configuration naming the cash-bill document type (INTERNAL_SALES_CASHBILL) and the status FINALCompany API — there is no screen for it, in Membership Admin or in OrganisationThe backend awards points only when the document’s type and posting status match this configuration. The default is INTERNAL_SALES_ORDER at FINAL — leave it unset and cash bills earn nothing
A price book with a POINT treatment (Point Currency GSPTS, Operator MULTIPLY, Value 1, Validity Period in days), selected as the POS Default PricebookPricebook; POS General → Default SelectionThis is what puts a point amount on each bill line; a member on a bill with no point amounts earns nothing. Leave Auto Apply Points From Pricebook switched on — it is a real gate, not a label: at finalise the backend reads that POS General setting and, if it is off, skips point generation for the bill entirely and says so only in the server log
A MEMBER_POINT_DISCOUNT item, set as the POS Points Discount Item CodeDoc Item Maintenance; POS General → Default SelectionNeeded only if you redeem points as a discount line rather than a settlement line
SHOW_MEMBER on in POS GeneralPOS General settingsShows the member panel at the counter

The loop

  1. Enrol at the counter. The cashier opens the member panel in POS General and creates the member: name, mobile number, IC or passport if that is the card-number rule. The class is the POS default (POS_DEFAULT_MEMBERSHIP_CLASS, say STANDARD) and the end date the POS default (POS_MEMBERSHIP_END_DATE). The record is the same bl_crm_membership_hdr row you would see in Membership Admin. A customer entity is optional; a scheduled processor can create and bind one later for members that have none.
  2. Sell. A flagship smartphone at RM 3,200 and a case at RM 89 go on the bill at GS-KV-01. Because the member is on the bill and the price book’s price set matches (Member Class rule STANDARD or GOLD, Branch rule, an absolute Valid Date Range), the POINT treatment writes a point amount and the currency GSPTS on each line, with validity dates from the treatment’s Validity Period (Days).
  3. FINAL. The cash bill posts revenue, stock-out and the cashbook exactly as a bill without a member would. Separately, the membership processor sees a document of the configured type at the configured status with a member and eligible lines, and writes one REWARD transaction line per bill line (3,289 points here). The lines’ point start and end dates become the lot’s validity. If none of the lines carries a point amount the document is left unmarked so a retry can pick it up.
  4. Balance. The running total in bl_crm_membership_points_current_balance and the per-lot control account are updated by a queue processor after the line is written. The member’s Point Transaction tab in Membership Admin shows the row with source, type and dates.
  5. Redeem on the next visit. The customer buys wireless audio for RM 249 and asks to use points. The cashier picks the member-points settlement button; the panel converts points to cash value through the PTS to CCY rate up to the maximum, and the balance is validated at FINAL. If the branch prefers the discount-line route, the MEMBER_POINT_DISCOUNT item carries the redemption as a line instead. Either way a REDEEM transaction line is written.
  6. Void. If a bill is voided, its point lines are reversed. If the reversal would take the balance below zero — the customer already spent the points — an adjustment line is added for the shortfall, so the balance is never silently negative.

What the ledger sees

The two membership document types, INTERNAL_MEMBERSHIP_POINT_REWARD and INTERNAL_MEMBERSHIP_POINT_REDEEM, carry an amount signum of 0 and a quantity signum of 0, and JournalPostingTypeHandler has no entry for either. Earning a point posts nothing. A redemption reaches the ledger only as the cash bill’s settlement line (a points settlement method) or as the points-discount line — both are the cash bill’s own posting, not the module’s. There is no “points liability” account in the product; if your accountant wants one, it is a manual journal from the balance query.

What does not happen

  • No tier is upgraded when the customer’s spend crosses a threshold; the class is what you set.
  • No welcome e-mail, SMS or physical card is generated by the module.
  • No “50 % of transaction” redemption cap exists; the POS points settlement has a maximum cash value and the balance check, nothing else.
  • Points do not expire “24 months from earning” unless the lot carries that end date — the POINT treatment’s Validity Period (Days), the adjustment’s Valid Date To or the CSV column set it, and the scheduled expiry processor then zeroes the lot.

Reports you can run

  • Membership Admin → Membership Report (CSV by date of birth, start, end, lifetime).
  • Sales Report → the member-reward-redemption route (points earned and redeemed by card, item and transaction type — present, not on the menu) and the POS General Z Report, which shows member-point discounts.
  • The API: …/membership-points-txn/current-balance/query and …/lines/query — see API Reference.