VIP tiers API

Auth: Clerk session.

CRUD

GET /v1/vip-tiers POST /v1/vip-tiers PATCH /v1/vip-tiers/:id

{
  "code": "platinum",                // immutable in PATCH
  "name": "Platinum",
  "rank": 3,
  "color": "#E5E4E2",
  "glyph": "★★★★",
  "requirements": {
    "lifetime_deposit_subunit": 5000000,    // €50000
    "lifetime_wagered_subunit": 25000000,   // €250000
    "min_days_active": 30
  },
  "demotion": { "inactivity_days": 45 },
  "perks": {
    "cashback_pct": 10,
    "dedicated_host": true,
    "priority_kyc": true
  },
  "is_active": true
}

Player tier

GET /v1/players/:id/tier

{
  "data": {
    "current_tier_code": "gold",
    "tier_promoted_at": "2026-04-15T...",
    "history": [
      {
        "from_code": "silver",
        "to_code": "gold",
        "trigger": "auto",            // auto | manual | reset
        "context": {},
        "occurred_at": "2026-04-15T..."
      }
    ]
  }
}

POST /v1/players/:id/tier — two modes:

// Manual override
{ "to_code": "platinum", "reason": "VIP host invitation" }

// Auto-recompute
{}

Manual override writes a trigger=manual history entry with the actor + reason. Subsequent auto-recompute respects the manual tier as the starting point.

Internal recompute

POST /v1/internal/recompute-tier (server-to-server):

{ "tenant_id": "uuid", "player_id": "uuid", "trigger": "auto" }

Used by stream-processor when wired (deferred default — see VIP tiers feature).