Affiliates

Run an affiliate marketing program where partners apply, create tracking links, earn commission on referred sales, and receive payouts.

The affiliates module gives you a full affiliate marketing program. Partners apply through your storefront, you approve them with a commission rate, and they create tracking links to share. When a referred visitor converts, a commission is calculated automatically. You review conversions in the admin and issue payouts up to each affiliate’s available balance.

Installation

npm install @86d-app/affiliates

Add the module to your store configuration:

import affiliates from "@86d-app/affiliates";

export default defineStore({
  modules: [
    affiliates({
      defaultCommissionRate: "10",
      minimumPayout: "50",
      cookieDurationDays: "30",
    }),
  ],
});

Configuration

defaultCommissionRate · string · default: "\"10\""

Default commission percentage applied to newly approved affiliates. For example, "10" means 10% of the referred order total.

minimumPayout · string · default: "\"50\""

Minimum payout amount in your store currency. Affiliates cannot receive a payout below this threshold.

cookieDurationDays · string · default: "\"30\""

How long the referral tracking cookie persists (in days). Conversions attributed after this window are not credited to the affiliate.

How it works

1. Apply

   Anyone submits an application via POST /affiliates/apply with their name, email, and optional website. Their account starts in pending status.

2. Approve

   An admin reviews the application and approves it, optionally setting a custom commission rate. The affiliate’s status moves to approved.

3. Create tracking links

   Approved affiliates create tracking links via POST /affiliates/links/create. Each link gets a unique 10-character slug for URL tracking.

4. Track clicks

   When a visitor clicks an affiliate link, a click is recorded via POST /affiliates/track. Both the link’s click count and the affiliate’s total click count are incremented.

5. Record conversions

   When a tracked visitor completes a purchase, a conversion is recorded with commission calculated as orderAmount × (commissionRate / 100).

6. Approve conversions

   An admin reviews and approves conversions. Approval updates the affiliate’s aggregate totals (conversions, revenue, commission).

7. Issue payouts

   An admin creates a payout up to the affiliate’s available balance (totalCommission − totalPaid). Marking a payout complete updates totalPaid.

Store endpoints

Method	Path	Description
POST	/affiliates/apply	Submit an affiliate application
GET	/affiliates/dashboard	Affiliate self-service dashboard
GET	/affiliates/my-links	List the authenticated affiliate’s tracking links
POST	/affiliates/links/create	Create a new tracking link
POST	/affiliates/track	Record a click on a tracking link

Submit an application (POST /affiliates/apply)

{
  "name": "Jane Doe",
  "email": "[e-mail]",
  "website": "https://janeblog.com"
}

Each affiliate receives a unique 8-character tracking code on application.

Admin endpoints

Method	Path	Description
GET	/admin/affiliates	List all affiliates
GET	/admin/affiliates/stats	Program-wide statistics
GET	/admin/affiliates/:id	Affiliate detail and current balance
POST	/admin/affiliates/:id/approve	Approve an application
POST	/admin/affiliates/:id/reject	Reject an application
POST	/admin/affiliates/:id/suspend	Suspend an approved affiliate
POST	/admin/affiliates/:id/update	Update affiliate fields
GET	/admin/affiliates/conversions	List conversions
POST	/admin/affiliates/conversions/:id/approve	Approve a conversion
POST	/admin/affiliates/conversions/:id/reject	Reject a conversion
GET	/admin/affiliates/links	List all tracking links
GET	/admin/affiliates/payouts	List payouts
POST	/admin/affiliates/payouts/create	Create a payout
POST	/admin/affiliates/payouts/:id/complete	Mark a payout as completed
POST	/admin/affiliates/payouts/:id/fail	Mark a payout as failed

Payouts cannot exceed an affiliate’s available balance (totalCommission − totalPaid). Attempting to create an overdraft returns null from the controller.

Types

type AffiliateStatus = "pending" | "approved" | "suspended" | "rejected";
type ConversionStatus = "pending" | "approved" | "rejected";
type PayoutStatus = "pending" | "processing" | "completed" | "failed";
type PayoutMethod = "bank_transfer" | "paypal" | "store_credit" | "check";

interface Affiliate {
  id: string;
  name: string;
  email: string;
  website?: string;
  code: string;           // Unique 8-character tracking code
  commissionRate: number;
  status: AffiliateStatus;
  totalClicks: number;
  totalConversions: number;
  totalRevenue: number;
  totalCommission: number;
  totalPaid: number;
}

interface AffiliateLink {
  id: string;
  affiliateId: string;
  targetUrl: string;
  slug: string;           // Unique 10-character URL slug
  clicks: number;
  conversions: number;
  revenue: number;
  active: boolean;
}

interface AffiliateConversion {
  id: string;
  affiliateId: string;
  linkId: string;
  orderId: string;
  orderAmount: number;
  commissionRate: number;
  commissionAmount: number;
  status: ConversionStatus;
}

interface AffiliatePayout {
  id: string;
  affiliateId: string;
  amount: number;
  method: PayoutMethod;
  reference?: string;
  status: PayoutStatus;
  paidAt?: Date;
}

interface AffiliateStats {
  totalAffiliates: number;
  activeAffiliates: number;
  totalClicks: number;
  totalConversions: number;
  totalRevenue: number;
  totalCommissionPaid: number;
}