Affiliate Program Management

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €49/mo; 50 affiliates included, commission rules, payout management

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

A paid module that lets merchants recruit influencers as affiliates, track affiliate sales with unique links, and automate commission payouts. Includes fraud detection and tax reporting (1099/CRS) for compliance.

The problem

Merchants want influencers to sell their products but have no way to recruit affiliates, track their performance, or calculate and pay commissions. They manually track affiliate sales in spreadsheets and send payments via PayPal without proof of income for tax purposes.

What it does

• Affiliate signup and approval workflow (merchants approve new affiliates, set commission tier per affiliate)
• Unique affiliate tracking link generation (each affiliate gets custom URL or coupon code)
• Sales attribution (assign order to affiliate if customer used their link or coupon within 30-day window)
• Commission calculation and payout (commission = order total * rate; auto-payout to affiliate bank account or PayPal)
• Affiliate dashboard (track commission earned, paid, pending; view top-performing links; request payout)
• Fraud detection (flag suspicious patterns: same IP as affiliate, rapid repeat orders, unusually high commission claims)
• Tax reporting (generate 1099-NEC for US affiliates, CRS for EU; include affiliate name, tax ID, earnings)
• Multi-tier commission structure (e.g., 10% for tier 1, 15% for tier 2 after $5k in sales)
• Commission hold period (hold payouts for 30 days in case of returns/chargebacks)
• Affiliate marketing assets (download pre-made banners, product images, email templates for affiliates)

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.

• Affiliate network integration (Impact, UpPromote; we own module, not third-party networks) — separate paid ‘affiliate-network’ module owns integrations
• Two-tier affiliate (affiliates recruit sub-affiliates) — paid ‘multi-level’ module owns MLM logic
• Predictive affiliate performance (ML to identify high-performers) — paid ‘advanced analytics’ owns ML models
• Affiliate content creation tools (built-in blog, email template WYSIWYG) — separate modules own content creation
• Commission holdback on return (deduct commission if order is returned; auto-reverse) — paid ‘returns-integration’ module owns order lifecycle hooks
• International tax forms (1099 is US-only; UK is CIS, Germany is different) — paid ‘tax-compliance’ module owns per-country forms

Data model

New entities: affiliates.program {id, merchantId, name, status (active/paused), commissionRate, holdPeriodDays, payoutSchedule (weekly/biweekly/monthly)}; affiliates.affiliates {id, programId, name, email, status (pending/approved/rejected/suspended), commissionTier, bankAccount{…}, paypalEmail, taxId, taxIdType, country}; affiliates.trackingLinks {id, affiliateId, slug, couponCode, expiresAt, isActive}; affiliates.attributions {id, orderId, affiliateId, trackingLinkId, attributionType (link/coupon), commissionAmount}; affiliates.commissions {id, affiliateId, periodStart, periodEnd, ordersAttributed, totalSalesAmount, commissionRate, commissionAmount, status (pending/approved/held/paid), payoutDate}; affiliates.fraudFlags {id, affiliateId, flagReason, severity (low/medium/high)}; affiliates.taxForms {id, affiliateId, year, formType (1099-nec/crs), sentToAffiliate}.

API

• POST /api/affiliates/program
• PATCH /api/affiliates/program/{id}
• POST /api/affiliates/affiliates
• GET /api/affiliates/affiliates
• PATCH /api/affiliates/affiliates/{id}
• GET /api/affiliates/affiliates/{id}/commissions
• POST /api/affiliates/tracking-links/{affiliateId}
• GET /api/affiliates/tracking-links
• POST /api/affiliates/commissions/calculate
• POST /api/affiliates/payouts
• GET /api/affiliates/fraud-flags
• POST /api/affiliates/tax-forms/{affiliateId}/{year}
• GET /api/affiliates/leaderboard

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

Admin

Affiliate program settings: set commission rate, hold period, payout schedule, tax form type. Affiliate approval queue: review signup requests, set commission tier, approve/reject/suspend. Commission calculation dashboard: preview pending commissions, approve/hold, trigger payout run. Fraud detection: review flagged affiliates with reason, approve or suspend. Tax reporting: generate 1099-NEC (US) or CRS (EU) per affiliate per year, download PDF or send via email. Payout tracking: view payout runs, status, proof of payment. Affiliate dashboard: show earnings, paid commissions, pending payouts, request payout.

The seam — why this is paid

Core owns free order tracking. Paid module owns affiliate credential management (bank account, tax ID storage with encryption), commission calculation and approval workflow (business logic, manual oversight), fraud detection (pattern matching, IP validation, hold rules), tax reporting (1099-NEC, CRS generation, filing support — legal compliance; merchants need support), payout orchestration to banks and PayPal (requires banking credentials and reconciliation).

Support commitment: affiliate fraud detection, payout SLA, tax reporting (1099/CRS)

Dependencies

• Orders module (to attribute orders to affiliates)
• Settings (to store commission rates, hold period, payout schedule)
• Email service (to send payout confirmations to affiliates, tax forms)
• Audit log (to track affiliate changes, commission approvals, fraud reviews)

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 affiliate signs up, gets ‘pending’ status; merchant approves to change status to ‘approved’
• An order placed with affiliate tracking link is attributed to that affiliate within 1 second of checkout
• A 30-day attribution window is applied: order from 30 days ago gets attributed to link; order from 31+ days ago does not
• Commission calculated as order total * affiliate rate; $100 order × 10% = $10.00 (integer cents stored)
• Payout run scheduled weekly sends all pending commissions to affiliate bank account or PayPal; status changes to ‘paid’
• Commission hold period of 30 days means pending commissions don’t payout until 30 days after order date
• A duplicate order from same IP as affiliate is flagged and requires merchant review before approval
• 1099-NEC is generated for US affiliates with >$600 annual earnings; form includes name, tax ID, total earnings
• Tax form is sent to affiliate email for review; affiliate must confirm receipt before merchant files
• Affiliate payout dispute: if affiliate claims $500 earned but system shows $400, merchant reviews order attribution and approves difference or rejects

Risks

Affiliate fraud: if same person signs up as merchant and affiliate, they can claim commission; IP/email deduplication required. Bank payout failure: if routing number is invalid, payout fails silently; retry logic and failure notification required. Tax form errors: if affiliate tax ID is wrong, tax filing fails; validate tax ID format. Commission hold period scope creep: if order is returned after 30 days, commission was already paid; need returns module integration to reverse. Chargeback fraud: if customer disputes order and initiates chargeback, affiliate commission was already paid; audit trail must show dates. International taxation: per-country obligations vary widely; don’t guess — payroll and 1099 forms differ per jurisdiction. Payout rate limiting: if 1000 affiliates pending payout, run may take hours; implement batch processing and progress tracking.

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.