Referral Program

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €29/mo; referral tracking, reward automation, fraud prevention

Generated from docs/plan/paid/referral-program/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid module that lets merchants incentivize existing customers to refer friends with automatic tracking of referrals and reward fulfillment. Includes fraud detection and referral deduplication for compliance.

The problem

Existing customers are happy to refer friends but merchants have no system to track referrals or reward them automatically. Merchants manually read customer emails asking ‘did my friend buy yet?’ and manually send discount codes or credits, losing data and fairness.

What it does

• Referral signup flow (existing customer gets unique referral link and QR code)
• Referral link tracking (when friend clicks link, referrer is recorded in session; if friend purchases within 30 days, referral is attributed)
• Referral reward fulfillment (auto-issue discount code or account credit to referrer and referee)
• Fraud detection (flag referrals from same IP, email domain, device; same-address orders; repeated self-referrals)
• Referral deduplication (if same person receives 3 referrals, only first referrer gets credit)
• Referral status tracking (pending, completed, paid, disputed)
• Reward tiers (e.g., ‘$10 off for both’ after first purchase; ‘$25 off for both’ after $100 spent)
• Referral history (existing customer sees their referrals, pending/completed count, rewards earned)
• Bulk referral seeding (merchant can manually add referrals; referee must opt-in to email)
• Referral analytics (viral coefficient: new customers per 100 existing customers, payback period)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Multi-level referrals (referral referral; referee becomes referrer) — separate ‘multi-level’ module owns MLM logic
• Predictive referral success (which customers are most likely to refer) — paid ‘predictive’ module owns ML models
• Referral ambassador program (tiered rewards for top referrers, exclusive perks) — paid ‘ambassador’ module owns this
• Referral social sharing (one-click share to Facebook, Instagram, email) — separate social integration module owns share widgets
• Real-time referral payout (same-day credit to account) — depends on order fulfillment state; paid ‘real-time-rewards’ owns this
• Referral fraud prevention ML (advanced pattern detection) — paid ‘advanced-fraud’ owns ML models; core has basic rules

Data model

New entities: referrals.program {id, merchantId, status (active/paused), referrerRewardType (discount/credit/coupon), referrerRewardAmount, refereeRewardType, refereeRewardAmount, rewardTier[], fraudDetectionRules[]}; referrals.referrers {id, programId, customerId, referralLink, referralCode, qrCodeUrl, createdAt}; referrals.referrals {id, referrerId, refereeEmail, refereeId (nullable), status (pending/completed/paid/disputed), attributionDate, rewardIssuedAt, flaggedForFraud}; referrals.fraudFlags {id, referralId, flagReason (same-ip/same-domain/same-device/same-address), severity, reviewedAt}; referrals.rewardDeduplication {id, refereeId, winningReferrerId, losingReferrerIds[], reason}; referrals.rewards {id, referralId, type (discount/credit/coupon), amount, expiresAt, usedAt, status (active/used/expired)}.

API

• POST /api/referrals/program
• PATCH /api/referrals/program/{id}
• POST /api/referrals/referrers/{customerId}
• GET /api/referrals/referrers/{customerId}
• GET /api/referrals/referrals
• PATCH /api/referrals/referrals/{id}/status
• GET /api/referrals/fraud-flags
• PATCH /api/referrals/fraud-flags/{id}
• POST /api/referrals/bulk-import
• GET /api/referrals/analytics
• POST /api/referrals/rewards
• GET /api/referrals/rewards/{id}

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Referral program settings: set reward types/amounts per tier, fraud detection rules. Referral list: view all referrals, status, attributed order, reward issued, fraud flags. Fraud review: view flagged referrals with reason, approve or reject. Bulk import: upload CSV of referrer/referee pairs, create pending referrals, send opt-in email. Referral analytics: viral coefficient, payback period, cost per referral, ROI. Customer referral dashboard: show customer their active referral link, referrals pending/completed, rewards earned.

The seam — why this is paid

Core owns free order tracking. Paid module owns referral program rules and tiers (business logic, customization, merchant support), fraud detection (IP/email/device/address matching — requires pattern analysis framework), referral deduplication (multi-first-attribution resolution — business rule enforcement), reward issuing (discount codes, store credit, coupon generation — integration with discount/coupon system), referral analytics (viral coefficient, payback period — requires cohort analysis).

Support commitment: referral deduplication, reward SLA, fraud detection

Dependencies

• Orders module (to attribute referral when referee purchases)
• Customers module (to identify referrer and referee)
• Discounts module (to issue discount codes and track usage)
• Email service (to send referral invite, reward claim, opt-in for bulk-imported referrals)
• Audit log (to track fraud flag changes, reward issuances)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• An existing customer generates a referral link unique to them; link contains ID and code
• When a friend clicks referral link and signs up, referrer is recorded in session; if friend purchases within 30 days, referral is attributed
• A referral with status ‘pending’ changes to ‘completed’ when referee’s order is confirmed
• Fraud flag ‘same-ip-as-referrer’ is set if referrer IP matches referee IP; merchant must review before reward payout
• A referral is deduplicated if referee receives 3 referrals; only first referrer gets credit
• Referrer and referee both receive reward after order is confirmed; rewards are issued as active discount codes
• A discount code reward with $10 value can be applied to any order and deducted from order total
• Referral analytics show viral coefficient: if 100 existing customers referred 25 new customers, coefficient = 0.25
• A fraud flag with ‘same-address’ reason is set if referrer and referee have matching billing address
• Bulk import of 1000 referrer/referee pairs creates 1000 pending referrals; opt-in email is sent to each referee within 1 hour

Risks

Self-referral fraud: if customer signs up with second email, they can refer themselves; email deduplication required. IP spoofing: VPN use defeats IP fraud detection; combine with device fingerprinting, email, address checks. Duplicate referral tracking: if deduplication rule is wrong, multiple rewards payout; last-attribution-wins must be enforced. Reward exhaustion: if referrer refers 1000 people and each gets $10 reward, cost = $10k; set per-referrer cap or per-program cap. Referral link expiration: if link never expires, referrer can earn credit for referrals 1 year later; set explicit expiration or activity decay. GDPR and CAN-SPAM: bulk-import email without consent violates law; require explicit opt-in confirmation. Multi-order deduplication: if referee purchases twice, is referral credited once or per purchase? Document and enforce rule. Reward payout on refund: if referee refunds, reverse the reward or mark as disputed.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.