Loyalty Rules Guide

Stackd supports two loyalty rule types: Stamp and Points. Each transaction type uses exactly one rule type. You cannot mix them on a single transaction type.

---

Stamp rules

Customers earn one stamp per qualifying transaction, regardless of spend amount. When the stamp count reaches the threshold, a reward is triggered.

Configuration

Field	Type	Description
Stamp threshold	Integer	Number of stamps that triggers the reward
Reward	Select	Which reward the customer receives at the threshold
Redemption mode	Enum	Immediate or Deferrable (see below)
Hard cut-off stamps	Integer (optional)	Stamps above threshold before automatic card reset

How stamps accumulate

Each successful transaction awards exactly one stamp. The running count is stored per customer per transaction type — a customer can have separate progress cards for each of your transaction types.

Example: threshold = 10

Stamp 1 → current: 1 / 10
Stamp 2 → current: 2 / 10
...
Stamp 10 → current: 10 / 10 → reward triggered

After a reward is confirmed, the stamp count resets to zero and a new card begins.

Redemption modes

Immediate — the reward is granted instantly when the threshold is reached. The customer sees the reward confirmation on their check-in screen and the operator sees it on the POS. No further action needed from the operator.

Deferrable — the reward is queued for fulfilment. The operator sees a pending reward notification on the POS and manually confirms fulfilment (e.g. after handing over the free coffee). The stamp count only resets after the operator confirms.

Hard cut-off

If you set a hard cut-off, stamps that accumulate beyond threshold + hard_cutoff_stamps trigger an automatic card reset and the reward is marked as lost. This prevents a customer from banking unredeemed rewards indefinitely.

Example: threshold = 10, hard cut-off = 5

• Stamps 1–10: normal accumulation
• Stamp 10: reward triggered
• Stamps 11–15: deferrable window; operator has not yet confirmed
• Stamp 16: card resets automatically, pending reward is marked lost

Leave hard cut-off blank if you want rewards to stay pending indefinitely until fulfilled.

Voiding a stamp transaction

If a transaction is voided, the stamp count is decremented by 1. The count never goes below zero.

---

Points rules

Customers earn points proportional to their spend amount. Points accumulate in a ledger and can be redeemed against rewards with a points cost.

Configuration

Field	Type	Description
Points per unit	Integer	Points awarded for each unit of spend
Unit amount (R)	Decimal	Rand value of one unit
Notification threshold	Integer (optional)	Notify customer by email when balance reaches this level

Points calculation

points = floor(spend_amount ÷ unit_amount) × points_per_unit

Example: spend R47, unit = R10, 5 points per unit

floor(47 ÷ 10) = 4 units
4 × 5 = 20 points awarded

The R7 remainder does not carry over — each transaction is calculated independently.

Points ledger

Points are stored in an append-only ledger. Every award and redemption creates a new row — rows are never updated or deleted. The displayed balance is the sum of all ledger entries for that customer.

Redeeming points

A customer redeems points by requesting a reward from the Rewards catalogue. Each reward has a points cost. If the customer's balance is sufficient and the reward is in stock, a redemption record is created.

The operator fulfils the redemption (hands over the reward) and marks it fulfilled on the POS dashboard or via the API. Points are deducted when the redemption is created, not when it is fulfilled.

Voiding a points transaction

If a transaction is voided, a negative ledger entry is written to reverse the awarded points. The customer's balance is recalculated from the full ledger sum.

---

Choosing between stamp and points

	Stamp	Points
Best for	Frequency reward (buy 10 get 1 free)	Spend-linked reward (earn R1 for every R10 spent)
Operator effort	Minimal — just enter the PIN	Enter spend amount before PIN
Customer perception	Simple counter, visible progress	Accumulating balance, flexible redemption
Reward trigger	Automatic at threshold	Customer-initiated redemption

Both rule types can coexist across different transaction types within the same business account. For example: Coffee transactions use stamps; Retail transactions use points.

---

Rewards catalogue

Rewards are configured separately from rules and can be shared across multiple points rules. Go to Admin → Rewards to manage your catalogue.

Field	Description
Name	Displayed to customers and operators
Description	Optional detail shown on check-in screen
Type	free_item, discount, voucher, experience
Points cost	Required for points rewards; not used for stamp rewards
Stock	Optional cap on total redemptions; null = unlimited
Active	Inactive rewards cannot be redeemed but history is preserved

When stock reaches zero, the reward becomes unavailable for new redemptions until stock is replenished or set to null.