Loyalty & referrals
Zubby ships a points-based loyalty engine and a give-and-get referral program that run on the same shopper profiles the AI already knows. Shoppers earn points from purchases and engagement, climb earn-rate tiers, and redeem points for discounts or free shipping — and the AI can reference a shopper’s balance and tier in conversation. This page covers all three surfaces: points, redemption rewards, and referrals.
Where it lives
Dashboard → Loyalty— program health: enrolled shoppers, points outstanding, points earned and redeemed in the last 7 days, the reward catalog, the tier ladder with member counts, and a recent-activity feed.Loyalty → Redemption tiers— the ladder of points-for-reward conversions shoppers can cash in.Loyalty → Referrals— referral program admin and a feed of recent referrals with conversion status.Settings → Loyalty— where you actually create rewards and edit earn-rate tiers. The main Loyalty page is read-mostly; the Configure tiers & rewards link sends you here.
How points are earned
Every points change is written to an immutable ledger. Each entry carries a sourceso you can audit exactly why a shopper’s balance moved. The sources are:
| Source | When it fires |
|---|---|
| Purchase | A completed order — the primary earn event. |
| Referral | An advocate’s referral converts. |
| Review | Shopper leaves a product review. |
| AI interaction | Qualifying engagement with the widget. |
| Signup bonus | One-time enrollment grant. |
| Tier bonus | Bonus applied for reaching a tier. |
| Manual adjustment | You credit or debit a balance by hand. |
| Reward redemption | Negative entry when points are spent. |
The dashboard’s Earned (7d) stat sums purchase points; Redeemed (7d) sums the absolute value of redemption entries. Each shopper has a single balance row tracking their current points balance and lifetime points (lifetime never decreases, even when they redeem).
Earn-rate tiers
Tiers are a loyalty ladder: pass a threshold of lifetime points and the shopper moves up. Each tier has a name, a threshold, an optional bonus multiplier on the earn rate (e.g. 1.50× means 50% more points per purchase), and a free-text perks description. The Loyalty page shows each tier with a live member count.
Two kinds of tier — don’t mix them up
Rewards & redemption tiers
Two related catalogs control what points buy. The reward catalog (shown on the Loyalty page, edited in Settings) lists named rewards with a points cost, an active toggle, and a times-redeemed counter. Reward types are:
- Percentage discount — a 0–100 percent off.
- Fixed discount — a flat amount, stored in cents.
- Free shipping — no value needed.
- Free product — tied to a product handle.
The dedicated Redemption tiers page is a leaner, ordered ladder of conversions sorted by points cost. Each tier has a name, a points cost, a reward kind (percent_off, fixed_off, free_shipping, or gift_card), a JSON reward value, and an active flag. Use it as the canonical “points → reward” menu shoppers see.
Referrals
A referral program is give-and-get: the advocate (an existing shopper) shares a code, and when a friendredeems it both sides get a reward. Configure a program with:
- Advocate reward and friend reward — each a reward definition (the two sides of give-and-get).
- Minimum purchase — an optional order floor (in cents) the friend must hit before the referral counts as converted.
- Active — the program on/off switch.
The Referrals page surfaces three counters — number of programs, total referrals, and converted referrals — plus a table of recent referrals showing the code, the friend’s email, status (pending → converted), and when it converted. Referral codes are unique per store.
Referrals feed loyalty
How the AI uses loyalty
Loyalty is not a silo. Because balances and tiers live on the shopper profile, the AI can mention a balance (“you have enough points for free shipping”), nudge a shopper toward the next tier, or time a referral ask after a great experience. Loyalty and VIP signals also flow into segments, so you can target “high points, no recent order” in a broadcast or a journey.
Gotchas
- The main Loyalty page is read-mostly. Reward creation and tier editing happen in
Settings → Loyalty— if the catalog or ladder is empty, that’s where to start. - Fixed discounts and minimum purchases are stored in cents. A
fixed_offvalue of500is $5.00, not $500. - Lifetime points drive tier thresholds and never decrease; redeeming only reduces the spendable balance.
- Points accrual on purchases requires the order to reach Zubby — that means the worker and the store connector have to be healthy.
Related
- Shoppers, lifecycle & VIP — VIP tiers and profile signals.
- Segments — target shoppers by loyalty and spend.
- Broadcasts — one-off campaigns to a segment.
- Affiliates — paid influencer links (distinct from referrals).