Skip to content

PR_DESCRIPTION.md

Latest commit

 

History

History
58 lines (36 loc) · 2.38 KB

PR_DESCRIPTION.md

File metadata and controls

58 lines (36 loc) · 2.38 KB
Raw

Implement Referral & Affiliate System

🎯 Overview

Incentivize growth by allowing users to earn a percentage of the platform fees generated by people they refer to LancePay. This system tracks referrals, generates unique codes, and automatically calculates earnings when invoices are paid.

✨ Features Implemented

Referral Management

  • ✅ Unique Code Generation: Every user is automatically assigned a unique alpha-numeric referral code (e.g., LANCE-ABC123).
  • ✅ Onboarding Tracking: Captured the "Referred By" relationship during user sign-up/onboarding via the referral stats route.
  • ✅ Privacy-Focused History: Implemented email masking (e.g., j***@gmail.com) for referral history to protect user data.

Affiliate Earnings Logic

  • ✅ Automated Commissions: Referral earnings are calculated at 10% of the platform fee (1% of invoice amount) whenever a referred user’s invoice is marked as PAID.
  • ✅ Real-time Stats: Aggregated stats including total referred users, total earned USDC, and pending payouts.

� Files Changed

Core Logic

  • lib/referral.ts: Core utility for code generation, commission calculation, and stats aggregation.

API Routes

  • app/api/routes-d/referrals/stats/route.ts: New route for both referral tracking (during onboarding) and viewing affiliate stats.

Testing

  • scripts/verify-referral.ts: Comprehensive verification script for the referral lifecycle.

🔗 New API Endpoint

  • GET /api/routes-d/referrals/stats?ref={CODE}
    • Captures referral code for new users.
    • Returns user-specific stats and referral history.

✅ Acceptance Criteria Met

  • Every user has a unique referral code.
  • Onboarding captures the referred_by_id.
  • Commissions are accurately calculated and recorded only when an invoice is fully paid.
  • Stats API returns accurate real-time aggregates.

🧪 Testing Checklist

  • ✅ Code Generation: Log in as a new user; verify a unique code is created.
  • ✅ Onboarding: Create a second user using the first user’s code; verify the relationship link.
  • ✅ Earning Trigger: Pay an invoice for the referred user; verify the commission in referral_earnings.
  • ✅ Leakage Control: Verified email masking in the history list.

PR Type: Feature Impact: High (Growth driver) Documentation: Updated lib/referral.ts and walkthrough.md.