Loyalty Program Guide

Points-based tier system. Users earn points on every bet, unlock tiers with multipliers and perks, and receive periodic cashback.

Works standalone - no challenge or funded account required.

---

How It Works

1. Operator configures points rate, tiers, and cashback in the backoffice
2. Every placed bet earns points (amount = stake * pointsPerEurWagered * tierMultiplier)
3. Points accumulate and unlock tier promotions
4. Higher tiers earn more points per bet (multiplier)
5. Cashback settles periodically (daily/weekly/monthly)
6. Optional point decay prevents inactive hoarding

---

Deployment Modes

Mode	Description
Challenges + Loyalty	Points earned on all bets. Tiers unlock challenge perks.
Loyalty only	Standalone tier system. Cashback as primary value.

---

Configuration

Global config (/v1/admin/loyalty/config)

Field	Description
pointsPerEurWagered	Base points per EUR staked (e.g. 1 = 1 point per EUR)
cashbackPercent	Base cashback rate (e.g. 2 = 2% of losses)
cashbackSettlement	Frequency: daily, weekly, or monthly
decayMode	none, monthly_percent, or monthly_reset
decayPercent	Points lost per decay cycle (if percent mode)

Tiers

Field	Description
name	Tier name ("Bronze", "Gold", etc.)
minPoints	Points threshold to enter tier
multiplier	Points multiplier (1.0, 1.5, 2.0, 3.0)
perks	Array of perk descriptions
icon	Icon name for widget

Example tiers:

Bronze:   0 pts,     1x multiplier
Silver:   1000 pts,  1.5x multiplier
Gold:     5000 pts,  2x multiplier, 3% cashback
Platinum: 20000 pts, 3x multiplier, 5% cashback, priority support

---

Points Mechanics

• Points earned = stakeInEUR * pointsPerEurWagered * tierMultiplier
• Only placed bets earn points (not settlements)
• Points are tenant-scoped (not shared across operators)
• Tier promotion: checked on every points award
• Tier demotion: checked on decay cycle (with optional grace period)

---

Cashback

• Accrues on losses during the settlement period
• Rate = cashbackPercent (may be tier-specific)
• Settlement fires loyalty.cashback_settled webhook
• Operator fulfills (credits the user's sportsbook balance)

---

API Reference

Operator (admin)

Method	Endpoint	Purpose
GET	/v1/admin/loyalty/config	Get loyalty config
POST	/v1/admin/loyalty/config	Set/update config
GET	/v1/admin/loyalty/tiers	List tiers
POST	/v1/admin/loyalty/tiers	Create a tier
PUT	/v1/admin/loyalty/tiers/:id	Update a tier
DELETE	/v1/admin/loyalty/tiers/:id	Delete a tier
GET	/v1/admin/loyalty/users	List loyalty members
GET	/v1/admin/loyalty/users/:userId	User loyalty detail
POST	/v1/admin/loyalty/users/:userId/adjust	Manually adjust points
GET	/v1/admin/loyalty/stats	Program statistics

Public (widget key)

Method	Endpoint	Purpose
GET	/v1/users/:userId/loyalty	User's points, tier, cashback
GET	/v1/loyalty/tiers	Public tier list (for widget)

---

SDK Usage

// Configure loyalty
await fast.admin.loyalty.setConfig({
  pointsPerEurWagered: 1,
  cashbackPercent: 2,
  cashbackSettlement: 'weekly',
  decayMode: 'monthly_percent',
  decayPercent: 10,
});

// Create tiers
await fast.admin.loyalty.createTier({ name: 'Gold', minPoints: 5000, multiplier: 2.0, perks: ['3% cashback', 'Priority support'] });

// Bonus points for VIP
await fast.admin.loyalty.adjustPoints('player-42', 1000, 'VIP welcome bonus');

---

Webhook Events

Event	When
loyalty.tier_upgraded	User promoted to higher tier
loyalty.tier_downgraded	User demoted (after decay)
loyalty.cashback_settled	Cashback credited to user

---

Reward Connection

• loyalty_points reward type adds points directly (from missions, achievements, etc.)
• Tier upgrades can trigger reward rules (e.g. "on Gold, grant free_bet")
• Cashback settlement emits webhook for operator fulfillment