@86d-app/affiliates

The Modern Foundation for Commerce

X · LinkedIn

This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.

Documentation: 86d.app/docs/modules/affiliates

@86d-app/affiliates

Affiliate marketing program module for the 86d commerce platform. Partners apply, get approved, create tracking links, earn commission on referred sales, and receive payouts.

Installation

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

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

Configuration

Option	Type	Default	Description
defaultCommissionRate	string	"10"	Default commission % for new affiliates
minimumPayout	string	"50"	Minimum payout threshold
cookieDurationDays	string	"30"	How long referral tracking cookie lasts

Store endpoints

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

Admin endpoints

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

Admin UI

The module includes admin UI components in src/admin/components/index.tsx (client components using useModuleClient):

Page	Component	Description
/admin/affiliates	AffiliateList	Affiliate list with stats, status management, and detail views
/admin/affiliates/applications	ApplicationList	Pending applications with approve/reject actions
/admin/affiliates/conversions	ConversionList	Conversion list with approve/reject actions
/admin/affiliates/payouts	PayoutList	Payout list with creation and status management

Controller API

interface AffiliateController {
  // Applications
  apply(params): Promise<Affiliate>
  getAffiliate(id): Promise<Affiliate | null>
  getAffiliateByCode(code): Promise<Affiliate | null>
  getAffiliateByEmail(email): Promise<Affiliate | null>
  listAffiliates(params?): Promise<Affiliate[]>
  approveAffiliate(id, commissionRate?): Promise<Affiliate | null>
  suspendAffiliate(id): Promise<Affiliate | null>
  rejectAffiliate(id): Promise<Affiliate | null>
  updateAffiliate(id, params): Promise<Affiliate | null>

  // Links
  createLink(params): Promise<AffiliateLink | null>
  getLink(id): Promise<AffiliateLink | null>
  getLinkBySlug(slug): Promise<AffiliateLink | null>
  listLinks(params?): Promise<AffiliateLink[]>
  recordClick(linkId): Promise<AffiliateLink | null>
  deactivateLink(id): Promise<AffiliateLink | null>

  // Conversions
  recordConversion(params): Promise<AffiliateConversion | null>
  getConversion(id): Promise<AffiliateConversion | null>
  listConversions(params?): Promise<AffiliateConversion[]>
  approveConversion(id): Promise<AffiliateConversion | null>
  rejectConversion(id): Promise<AffiliateConversion | null>

  // Payouts
  createPayout(params): Promise<AffiliatePayout | null>
  getPayout(id): Promise<AffiliatePayout | null>
  listPayouts(params?): Promise<AffiliatePayout[]>
  completePayout(id): Promise<AffiliatePayout | null>
  failPayout(id): Promise<AffiliatePayout | null>

  // Stats
  getStats(): Promise<AffiliateStats>
  getAffiliateBalance(affiliateId): Promise<{ totalCommission, totalPaid, balance }>
}

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"

How it works

1. Apply — Anyone submits an application with name, email, optional website
2. Approve — Admin reviews and approves with a commission rate (default 10%)
3. Links — Approved affiliates create tracking links to specific pages/products
4. Clicks — When visitors click affiliate links, clicks are tracked
5. Conversions — When tracked visitors purchase, a conversion is recorded with calculated commission
6. Approve conversion — Admin reviews and approves conversions, updating affiliate totals
7. Payouts — Admin creates payouts up to the affiliate's available balance
8. Complete — Payout is marked complete, updating the affiliate's totalPaid

Notes

• Commission is calculated at conversion time: orderAmount * (commissionRate / 100)
• Affiliates can only create links and earn conversions while in approved status
• Payouts cannot exceed totalCommission - totalPaid (no overdraft)
• Each affiliate gets a unique 8-character tracking code on application
• Each link gets a unique 10-character slug for URL tracking