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.

Stamp card expiry (inactivity reset)

Optionally, a stamp card in progress can be reset to zero if the customer hasn't transacted at your business for a chosen number of months. This is off by default — turn it on from Admin → Transaction Types & Rewards → Progress expiry if you want it.

Only affects in-progress cards (current_stamps > 0). Completed/redeemed cards are never touched, and this setting has no effect on points.
Checked once a day. A customer who transacts again before the inactivity window is up keeps their progress — the clock resets on every transaction.
Every automatic reset is logged for audit, including how many stamps were lost and why.
The duration follows the platform-wide default unless you set your own override.

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.

Points 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.

Points expiry (earn-window)

Optionally, points can expire a set number of months after they're earned — not based on overall inactivity. This is off by default — turn it on from Admin → Transaction Types & Rewards → Progress expiry if you want it.

Each batch of points a customer earns gets its own expiry date, fixed at the moment it's earned. Changing your expiry duration later only affects points earned from that point forward — it never reshuffles the expiry date on points customers already hold.
Redemption always spends a customer's oldest points first (FIFO), so the points closest to expiring are used before newer ones.
Checked once a day. When a batch's window passes, any still-unspent points from that batch are removed from the balance and a line item is written to the ledger explaining what expired and when it was earned.
If a redeemed reward is later voided, the refunded points are treated as a fresh batch earned today, with a new full expiry window — not a restoration of whichever older batch(es) originally funded the redemption.

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 | stamp or points — matches the rule type it's used with | | 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.

← Help