Affiliates

Affiliation Program

Account-centric partner program for marketers and content creators. Distinct from referrals: cash commissions settled manually in each original billing currency (not in-app credits), application + admin approval required, and tier-based commission models (recurring monthly or one-time upfront). The system is feature-gated via the AFFILIATES_ENABLED environment variable (server-only) and surfaces as 404 when disabled. Stripe Connect is intentionally not part of this workflow.

Feature Gate

Set AFFILIATES_ENABLED=true to activate the public landing page, application form, user dashboard, tracking redirect, and admin console. The flag is read once inside config/affiliates.ts and exposed as affiliatesConfig.enabled / isAffiliatesEnabled(). A second env var AFFILIATES_SALT (server-only, exactly 64 hexadecimal characters, distinct from REFERRAL_SALT and LOGS_SALT) authenticates click timestamps and hashes visitor IPs before storage.

Upgrade note: the signed-cookie release intentionally rejects legacy plain-code bsk_aff cookies. Existing visitors must revisit an affiliate URL to receive a signed cookie; already-persisted affiliate_attributions and their qualified recurring subscriptions are unaffected. Announce or stage this one-time reset before deployment if the program is already active.

Configuration (config/affiliates.ts)

Per-Tier Commission Model

The subscriptionModel field decides what happens on subscription invoices. Per-affiliate overrides on the affiliates row (subscription_model_override, upfront_multiplier_override, hold_period_days_override, default_commission_pct, cookie_window_days) win over the tier defaults.

Attribution Flow

1. Visitor hits /?aff=ABCD123XYZ  or  /[locale]/affiliate/ABCD123XYZ
            │
            ▼
2. Proxy / route — Zod-validates the code, signs the click timestamp and sets
   the httpOnly bsk_aff cookie (Secure, SameSite=Lax). Tracking redirect fires
   record_affiliate_click RPC (fire-and-forget).
            │
            ▼
3. Authenticated user starts checkout for a server-authorized billing Account
            │
            ▼
4. Checkout authenticates and consumes bsk_aff before creating the Stripe
   session. Onboarding also calls POST /api/affiliates/attribute as a legacy
   reconciliation fallback. Self-referral, same-owner, expired-click,
   one-per-lifetime and IP rate-limit guards.
            │
            ▼
5. affiliate_attributions row inserted (status='active', expires_at
   = signed click time + per-tier cookieWindowDays). Persistent record —
   survives browser-cookie deletion.
            │
            ▼
6. When billing event fires (Stripe webhook), maybeRecordAffiliateConversion
   resolves attribution + tier policy + commission math, calls
   record_affiliate_conversion RPC. Idempotent on stripe_event_id. A
   subscription first qualified inside the window remains eligible for its
   configured 12/24 invoice cap; expiry still blocks a new subscription or
   new one-shot purchase.
            │
            ▼
7. Daily cron reconciles canonical payment proofs and missed reversals, then
   flips eligible pending conversions to approved after the hold period.
   Refunds / lost disputes call reverse_affiliate_conversions_by_source.

Database Schema

Eight tables, all RLS-enabled with SELECT policies scoped by membership. Writes go exclusively through SECURITY DEFINER RPCs (no INSERT/UPDATE/DELETE policies). affiliate_clicks has zero policies — service-role only (high-volume internal table).

SECURITY DEFINER RPCs

Every RPC runs REVOKE EXECUTE FROM authenticated, anon; GRANT TO service_role; with an auth.role() defense-in-depth check. Stable error code strings (AFFILIATE_*) are mapped back to typed AffiliateError in core/affiliates/error-codes.ts and translated via errors.affiliate_* i18n keys.

Stripe Webhook Integration

Billing hooks call maybeRecordAffiliateConversion from core/billing/mutations.ts after every credit-granting hook. Refund reversals run from the refund path, and lost-dispute reversals run from core/billing/risk-events.ts through reverseAffiliateConversionsBySource. All affiliate hooks are wrapped in try/catch + logError — affiliate failures NEVER break billing. Cache invalidation (revalidateAffiliateStats) fires on success.

User Dashboard

The user-facing dashboard at /private-dashboard/affiliates branches on application state and provides link creation/copying, terms re-acceptance, recent conversions, and commission totals separated by currency. Per-status conversion KPIs come from the affiliate_conversion_stats_by_status RPC in one round-trip.

Admin Console

The admin panel at /admin-dashboard/affiliates renders three sections in parallel via Promise.all: pending-applications queue with approve/reject dialogs (tier dropdown + reason textarea), active-affiliates list with tier + status + lifetime totals, and a recent-conversions table with manual reverse action. Every admin mutation writes an admin_logs row with { actor_user_id, action, target_type, target_id, details: { reason, before } }.

Background Jobs

API Endpoints

Environment Variables

Security Invariants

• Self-attribution blocked at the RPC level (account-id check + same-owner check on accounts.owner_user_id)
• One attribution per account for life (UNIQUE(referred_account_id)) — prevents farming via re-attribution
• One affiliate per account (UNIQUE(affiliates.account_id)); one pending application at a time (partial UNIQUE)
• stripe_event_id UNIQUE on conversions — replayed Stripe webhooks no-op without double-incrementing affiliate aggregates
• IP + User-Agent stored as SHA-256 hashes salted with AFFILIATES_SALT — never raw PII; hash helper degrades to null when salt unset (graceful)
• commission_pct snapshotted on every conversion row — config edits never retroactively change historical commissions
• The cookie click timestamp is HMAC-authenticated; unsigned cookies are rejected and cannot extend a tier window
• Attribution expiry blocks a new subscription or one-shot purchase, but does not truncate an already-qualified recurring subscription
• Refunds and lost disputes automatically reverse all matching conversions for credit_pack + license sources via reverse_affiliate_conversions_by_source
• Every admin mutation (approve / reject / reverse) writes an admin_logs entry with a before-snapshot
• Feature gate returns 404 (not 403) so the surface is invisible when disabled
• CSRF + rate limit enforced on every state-changing endpoint via apiSecurity.*
• Affiliate webhook hooks wrapped in try/catch + logError — affiliate failures NEVER break billing