Last verified: 2026-05-19
Loyalty program (admin)
Create and configure an organization loyalty program: earning rates, tiers, rewards, and redemption rules.
Feature gate
Requires subscription feature enableLoyaltyProgram. Without it, the loyalty area is hidden or shows upgrade prompts.
Dashboard path
/admin/loyalty (staff mirror: /staff/loyalty when permitted).
Limits
- One loyalty program per organization (UI disables Create Loyalty Program when a program already exists for the org).
- Plan may cap programs via
ResourceType.LOYALTY_PROGRAM— upgrade if create is blocked.
List view
- Search: Search loyalty programs...
- Status filter: all / active / inactive
- Analytics: total programs, active programs, points configuration summary
- Program table columns include name, earning rate, minimum redemption, Active / Inactive badge
- Row actions: Edit loyalty program (wizard) (settings icon), Delete loyalty program
Primary action: Create Loyalty Program
Wizard steps (create / edit)
The Loyalty Program modal runs as a 5-step wizard:
| Step | Name | Purpose |
|---|---|---|
| 1 | Basic Setup | Program name, description, points per currency, currency units, expiration, minimum redemption, active flag |
| 2 | Customer Tiers | Tier levels (e.g. Silver, Gold) |
| 3 | Rewards | Redeemable rewards |
| 4 | Earning Rules | When points are earned |
| 5 | Advanced | Caps, referral/birthday bonuses, transfer settings, fraud detection |
Step 1 — required fields
- Program name
- Points (must be > 0)
- Currency units (must be > 0) — spend amount that earns the configured points
Optional/advanced on later steps: maxPointsPerOrder, maxRedemptionPercent, referralBonusPoints, birthdayBonusPoints, allowPointTransfer, fraudDetectionEnabled, daily caps, etc.
Steps — create a program
- Open
/admin/loyalty. - Click Create Loyalty Program.
- Complete Basic Setup and proceed (wizard auto-saves when advancing in create mode).
- Configure tiers, rewards, earning rules, and advanced settings.
- Ensure Active is enabled for customers to earn/redeem.
- Finish wizard and confirm program appears in the list as Active.
Steps — manual point adjustment
Use Customer management → Adjust Loyalty Points for individual customers.
Customer-facing behavior
- Customers view balances at
/customer/loyalty-program. - Storefront checkout can apply loyalty redemption when programs and accounts exist.
Verify it worked
- Program shows Active in
/admin/loyalty. - Test order earns points (per earning rules).
- Customer detail Loyalty tab shows balance and transactions.
Common issues
| Symptom | Likely cause | What to do |
|---|---|---|
| Page empty / upgrade | Feature not on plan | Enable enableLoyaltyProgram or upgrade |
| Cannot create second program | One program per org | Edit existing program |
| Wizard won't advance | Missing step 1 fields | Fill name, points, currency units |
