BUY-2529: Developer Referral Loop — API Key Sharing Incentive

Context

BuyWhere needs a viral growth mechanism for its agent-native product catalog API targeting Singapore developers. The goal is to leverage existing developers as advocates who can earn API credits by referring new developers, while giving new developers an instant benefit (bonus credits) to kickstart their integration.

Design Principles

1. Zero-friction referral flow — Sharing a link or API key should be trivial
2. Dual-sided incentive — Both referrer and referee benefit immediately
3. Transparent tracking — Developers can see referral stats and earnings
4. Abuse prevention — One-time credits per developer, no self-referral
5. API-first — All operations accessible via REST API for automation

Data Model

Developer

{
  "id": "dev_abc123",
  "email": "dev@example.com",
  "name": "Developer Name",
  "referred_by": "dev_xyz789",
  "referral_code": "ALICE2024",
  "referral_credits_earned": 5000,
  "referral_credits_used": 1200,
  "referral_credits_balance": 3800,
  "referred_developers_count": 12,
  "created_at": "2026-01-15T10:00:00Z"
}

ReferralCredit Ledger

{
  "id": "rc_001",
  "referrer_id": "dev_abc123",
  "referee_id": "dev_def456",
  "credit_amount": 500,
  "reason": "referral_signup",
  "created_at": "2026-04-01T10:00:00Z"
}

ReferralCode

{
  "code": "ALICE2024",
  "developer_id": "dev_abc123",
  "is_active": true,
  "max_uses": null,
  "uses_count": 12,
  "created_at": "2026-01-15T10:00:00Z"
}

API Endpoints

POST /v1/developers/referral-code

Generate or retrieve your referral code.

curl -X POST https://api.buywhere.ai/v1/developers/referral-code \
  -H "Authorization: Bearer bw_live_xxx"

Response:

{
  "referral_code": "ALICE2024",
  "referral_url": "https://api.buywhere.ai/signup?ref=ALICE2024",
  "share_text": "Build AI shopping agents with @buywhere API — Singapore's product data layer. Use my referral code ALICE2024 for 1000 bonus credits on signup! https://api.buywhere.ai/signup?ref=ALICE2024",
  "total_referrals": 12,
  "credits_earned": 6000,
  "credits_available": 3800
}

GET /v1/developers/referrals

List your referrals with status and credit history.

curl https://api.buywhere.ai/v1/developers/referrals \
  -H "Authorization: Bearer bw_live_xxx"

POST /v1/developers/signup (with referral)

New developer signup with optional referral code.

curl -X POST https://api.buywhere.ai/v1/developers/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newdev@example.com",
    "password": "secure-password",
    "name": "New Developer",
    "referral_code": "ALICE2024"
  }'

GET /v1/developers/referral-stats

Detailed analytics for referral program.

curl https://api.buywhere.ai/v1/developers/referral-stats \
  -H "Authorization: Bearer bw_live_xxx"

DELETE /v1/developers/referral-code

Revoke your referral code.

curl -X DELETE https://api.buywhere.ai/v1/developers/referral-code \
  -H "Authorization: Bearer bw_live_xxx"

Incentive Tiers

Credit System

• Credits are additive — earned credits never expire
• Credits apply against API usage (1 credit ≈ 1 API call for rate limit purposes)
• Referrer credits are granted incrementally as referee hits milestones
• Credits cannot be converted to cash — they are API credits only

Abuse Prevention

1. One-time per developer — Referral code can only be used once per email domain
2. Self-referral detection — Same email domain cannot refer itself
3. Credit vesting — Credits for milestones vest over 7 days (reversal if abuse detected)
4. Rate limiting — Signup endpoint rate limited to 10/hour per IP
5. Fraud signals — Email domain age, disposable email detection

Implementation Phases

Phase 1: Core Referral Loop (MVP)

• POST /v1/developers/referral-code — Generate personal referral code
• POST /v1/developers/signup with referral_code parameter
• Automatic credit award on successful referral
• Basic referral list endpoint

Phase 2: Tracking & Analytics

• GET /v1/developers/referrals — Detailed referral list
• GET /v1/developers/referral-stats — Analytics dashboard
• Milestone-based credit awards (first API call, active usage)

Phase 3: Sharing & Promotion

• Pre-formatted share text for Twitter/LinkedIn/Telegram
• Share buttons on developer dashboard
• Leaderboard of top referrers (optional, community aspect)

Security Considerations

• Referral codes are unique and case-insensitive
• API key authentication required for all referral endpoints
• Referral credit ledger is append-only (immutable audit trail)
• Credits cannot be transferred between developers
• All PII in referral responses is masked (email shown as user***@domain.com)

Example Developer Flow

1. Alice generates referral code ALICE2024 via API
2. Alice shares code on Twitter/X and LinkedIn
3. Bob signs up using ALICE2024, gets 1,000 bonus credits
4. Alice automatically receives 500 credits when Bob signs up
5. Bob makes first API call — Alice receives 500 more credits
6. Alice checks referral stats, sees 12 referrals and 3,800 available credits
7. Alice uses 3,800 credits for higher rate limits on her shopping agent