Loyalty Points, VIP Tiers & Rewards

Paid pluginsize Lplanned, not built

Indicative price, not an offer: $29-79/mo; anchor: Smile $29 entry tier

Generated from docs/plan/paid/loyalty-points-vip-tiers-rewards/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid module that layers VIP tier progression, referral bonuses, and point expiration on top of the core loyalty-points-program. Customers earn tier status (bronze → silver → gold) based on lifetime spend; VIP tiers unlock exclusive perks (early access to sales, free shipping, multiplier points). Referral links award both referrer and new customer points. Points auto-expire after 2 years unless configured otherwise.

The problem

Core loyalty points are simple (earn 1 pt per €1, redeem), but competitive programs reward high-value customers with exclusive perks and tiers to encourage repeat buying. A ‘VIP gets free shipping’ or ‘refer a friend for 100 points’ requires manual tracking and enforcement currently absent.

What it does

• VIP tier progression: define tiers (bronze: €0+, silver: €500+, gold: €2000+ lifetime spend)
• Tier perks: free shipping, 2x points multiplier, early sale access, exclusive discount codes
• Automatic tier assignment: when customer’s lifetime_spend >= tier_threshold, promote to tier
• Tier demotion: if spent amount drops (rare, but possible with refunds), demote tier
• Referral rewards: generate unique referral link per customer, award 100 points to referrer and new customer on first purchase
• Fraud prevention: one IP address cannot create 10 referral accounts in 1 hour (velocity check)
• Point expiration: points earned on Jan 1 expire on Jan 1 (2 years later) unless merchant disables expiration
• Audit trail: log tier changes, referral links used, point expiration events

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Birthday bonuses (too specific; out of scope)
• Social media integration (sharing referral link on Twitter, etc.; storefront owns this)

Data model

Add loyalty_tiers table: { id, shop_id, tier_name, threshold_minor_units, points_multiplier, perks (JSON: {free_shipping: true, early_access: true}) }. Add customer.loyalty_tier_current and loyalty_tier_changed_at. Add referral_links table: { id, referrer_customer_id, referral_code, referred_customer_id, referred_at, referrer_reward_claimed, referred_reward_claimed }. Add points_history.expires_at (timestamp). Schema migration: add tier fields to customer, create new tables.

API

• GET /account/loyalty/tiers — read all tiers and current tier status
• GET /account/loyalty/referral-link — generate unique referral code for customer
• POST /signup?referral_code=XXXX — new customer uses referral code, both parties get points
• GET /admin/loyalty/tier-rules — read tier definitions
• PUT /admin/loyalty/tier-rules/:tierId — edit tier thresholds and perks
• GET /admin/loyalty/referrals — list all referrals, rewards claimed, and fraud flags

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Add ‘VIP Tiers’ section in Commerce > Loyalty. Define tiers: name, spend threshold (€), points multiplier, perks (checkboxes). Point expiration toggle and months-to-expiration slider (default 24). Dashboard: show tier distribution (X% bronze, Y% silver, Z% gold), average lifetime spend by tier. Referral dashboard: total referrals, referral acceptance rate, fraud flags (velocity alerts).

The seam — why this is paid

Paid module owns tier logic, referral system, point expiration, and fraud prevention. Core loyalty-points-program owns base point earning/redemption; this module adds advanced retention mechanics.

Paid module owns point accrual tracking, tier progression logic, VIP access control, and referral reward processing; commerce-adjacent logic beyond core order interface

Dependencies

• loyalty-points-program (must be installed first; this module builds on it)
• Customer lifetime_spend tracking (must exist to determine tier)
• Audit log system (to track tier changes)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Customer with €500 lifetime spend is automatically promoted to Silver tier; points now earn at 1.5x multiplier
• Referral link generated: customer@example.com gets code REF_ABC123, shares with friend
• Friend uses REF_ABC123 at signup, makes €50 purchase; both customer and friend get 100 points, referral_links.referred_customer_id is set
• Two referral signups from same IP within 1 hour are flagged for fraud review in admin
• Points earned on Jan 1, 2024 expire on Jan 1, 2026 (24 months later) unless merchant extends
• Admin dashboard shows ‘Silver tier: 35% of customers, avg spend €650, 2.5x ROI vs Bronze’

Risks

If tier demotion is automatic (customer gets refund, spend drops below threshold), customer frustration (communicate demotion clearly). If referral code is not unique or is guessable (use 12-char alphanumeric, generate cryptographically), fraud is easy. If point expiration is retroactive (old points suddenly expire mid-month), customer confusion increases.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.