Skip to content

Loyalty & gamification

All of this is owned by the fruitplug-api plugin and stored in the WP MySQL DB. See data model for the tables.

Plug Points

1 point per £1 spent. 10 points = £1 off.

flowchart LR
  A[Order status → completed] --> B[woocommerce_order_status_completed hook]
  B --> C[PointsLedger::award_for_order]
  C --> D[(wp_fruitplug_points_ledger<br/>+delta = order_total)]

Balance = SUM(delta) WHERE user_id = ?. The ledger is append-only.

Streaks

Daily cron computes: for each user with a completed order this ISO week, increment current_length by 1. If they missed a week, reset to 0.

Tiers derived from current_length:

Tier Weeks in a row
Bronze 1–3
Silver 4–7
Gold 8–15
Plug VIP 16+

Fruit Passport

Every unique product you've ordered earns a stamp. Collect a full row for a reward (e.g. try all 5 dragon fruits → free upgrade next box).

Stamps live in wp_fruitplug_passport with times_ordered incremented on each re-order.

Referrals

  • Customer taps Share → /wp-json/fruitplug/v1/referrals/code returns their unique code (created lazily).
  • Referee enters code at checkout → code saved to order meta.
  • On referee's first completed order, the ledger credits both parties with 1,000 points (£100 off in points; adjust if you prefer £10 cash-off).

Spin-to-win

Triggered at:

  • First-ever visit (conversion hook)
  • After 3rd, 5th, 10th orders (retention hooks)

Prizes are entries in the points ledger (reason=spin_reward).

Admin UI

Phase 2 deliverable: a small admin page inside WP admin (Tools → Fruit Plug) showing:

  • Live points distribution (histogram)
  • Top 20 referrers
  • Passport completion stats
  • Streak-leaderboard

Until then, all data is queryable directly via SQL on the WP DB.