From 3bd4b12a5138483b987e43eb3924def673e33049 Mon Sep 17 00:00:00 2001 From: Dwindi Ramadhana Date: Wed, 3 Jun 2026 15:02:27 +0700 Subject: [PATCH] docs: Update affiliate documentation with Link Builder, Curated Collections, and Smart Links --- docs/marketing/affiliates.mdx | 220 +++++++++++++++++++++++++++++++--- 1 file changed, 201 insertions(+), 19 deletions(-) diff --git a/docs/marketing/affiliates.mdx b/docs/marketing/affiliates.mdx index 5a7be58..5e8ff14 100644 --- a/docs/marketing/affiliates.mdx +++ b/docs/marketing/affiliates.mdx @@ -1,30 +1,212 @@ --- title: Affiliate Program -description: Manage referral tracking and commissions for your store. +description: Manage referral tracking, commissions, and payouts for your store's affiliate partners. --- -> [!NOTE] -> **Status:** Planning / Upcoming Feature -> The Affiliate Program module is currently in development and will be available in a future release. +# Affiliate Program The WooNooW Affiliate Program allows you to build a network of partners who earn commissions by referring customers to your store. This feature is fully integrated into the WooNooW Admin SPA and Customer Dashboard. -## Overview +## Commission Rate Hierarchy -The affiliate system will handle referral tracking, commission calculation, and payout management without needing external plugins. +The affiliate system uses a **3-level priority hierarchy** for commission rates. This allows granular control over how much affiliates earn for each sale. -### Planned Features +``` +┌─────────────────────────────────────────────────────────┐ +│ COMMISSION RATE PRIORITY │ +├─────────────────────────────────────────────────────────┤ +│ 1. Product-Specific Rate (Highest Priority) │ +│ └─ Only used if product has "Enable affiliate │ +│ commission" checked AND has a custom rate set │ +│ │ +│ 2. Affiliate Custom Rate │ +│ └─ Set per-affiliate in Admin > Marketing > │ +│ Affiliates > Edit individual affiliate │ +│ │ +│ 3. Global Default Rate (Lowest Priority / Fallback) │ +│ └─ Set in Admin > Marketing > Affiliate Settings │ +│ (Default: 10%) │ +└─────────────────────────────────────────────────────────┘ +``` -1. **Referral Tracking**: Cookie-based tracking (e.g., 30 days) to accurately attribute sales to affiliates. -2. **Commission Management**: Set flexible commission rates for successful referrals. -3. **Admin Management UI**: - * Review and approve affiliate applications. - * Monitor referral history and earnings. - * Process payouts directly from the admin dashboard. -4. **Customer Dashboard Integration**: - * Affiliates can access their unique referral links and codes from their account page. - * View real-time statistics (clicks, conversions, pending earnings). - * Submit payout requests. -5. **Automated Notifications**: Trigger emails or notifications when a referral is completed or a payout is processed. +### How Commission is Calculated -*More details will be provided once the module is officially released.* +When an affiliate's referral makes a purchase: + +1. **The system checks each line item in the order** (for orders with multiple products) +2. **Each product gets its commission rate determined individually**: + - If the product has affiliate enabled with a custom rate → Use that rate + - Else if the affiliate has a custom rate → Use affiliate's rate + - Else → Use global default rate +3. **Commission is calculated per item**: `commission = (item_total × rate) / 100` +4. **Total commission = sum of all item commissions** + +### Example Scenario + +| Product | Affiliate Enabled | Product Rate | Affiliate Rate | Global Rate | Affiliate Earns | +|---------|-------------------|--------------|---------------|-------------|-----------------| +| Product A | Yes | 30% | 15% | 10% | **30%** | +| Product B | No | — | 15% | 10% | **15%** | +| Product C | No | — | — | 10% | **10%** | + +For an order containing all three products with a subtotal of Rp 100.000 each: +- Product A: Rp 100.000 × 30% = Rp 30.000 +- Product B: Rp 100.000 × 15% = Rp 15.000 +- Product C: Rp 100.000 × 10% = Rp 10.000 +- **Total commission: Rp 55.000** + +## Setting Up Commission Rates + +### Global Default Rate + +Set the default commission rate for all products and affiliates: + +1. Go to **Admin > Marketing > Affiliate Settings** (or Module Settings) +2. Find **Default Commission Rate** field +3. Enter percentage (e.g., `10` for 10%) +4. Save changes + +> [!TIP] +> The global default is used when no product-specific or affiliate custom rate is set. + +### Per-Product Commission Rate + +Override the commission for specific products: + +1. Go to **Admin > Products** and edit a product +2. In the **General** tab, scroll to the **Affiliate** section +3. Check **"Enable affiliate commission for this product"** +4. Enter a custom **Commission Rate (%)** +5. Save the product + +``` +Product: Premium T-Shirt +├── Price: Rp 150.000 +├── Affiliate: Enabled ✓ +└── Custom Rate: 25% + +When affiliate's referral buys this: +→ Affiliate earns 25% of Rp 150.000 = Rp 37.500 +``` + +> [!NOTE] +> If you enable affiliate commission but leave the rate empty, the system will fall back to the next level in the hierarchy (affiliate custom rate → global default). + +### Per-Affiliate Custom Rate + +Override the commission for a specific affiliate: + +1. Go to **Admin > Marketing > Affiliates** +2. Click on the affiliate in the list +3. Find the **Rate** column +4. Click the pencil icon to edit +5. Enter a custom percentage (e.g., `15`) +6. Click **Save** + +> [!TIP] +> A "(custom)" label appears next to custom rates, while "(default)" indicates the affiliate is using the global rate. + +## Referral Tracking Flow + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Customer │ │ Affiliate │ │ Customer │ │ Order │ +│ clicks ref │ │ shares URL │ │ makes purch│ │ created │ +│ link ?ref= │────▶│ w/ code │────▶│ via cookie │────▶│ + tracking │ +│ ABC123 │ │ │ │ stored │ │ recorded │ +└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ + │ + ▼ +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Payout │ │ Commission │ │ Referral │ │ Referral │ +│ processed │ │ approved │ │ approved │ │ pending │ +│ to │◀────│ after 14 │◀────│ (if order │◀────│ (after │ +│ affiliate │ │ days hold │ │ not refund)│ │ conversion)│ +└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ +``` + +## Link Sharing & Collections + +To help affiliates market your products more effectively, WooNooW provides advanced tools for link generation and product curation directly in their dashboard. + +### Link Builder + +The Link Builder allows affiliates to generate trackable links to *any* page on your site, not just the homepage. + +- **Custom Destination**: Affiliates can paste any store URL (e.g., a specific product or category page) to generate a referral link. +- **Campaign Tracking**: Affiliates can optionally append campaign parameters (e.g., `&campaign=summer-sale`) to track which marketing efforts are driving conversions. +- **One-Click copy**: Generated links can be copied to the clipboard instantly. + +### Curated Collections + +Instead of sharing links to individual products, affiliates can build custom "Collections" of products to share with their audience. + +- **Collection Builder**: Affiliates can browse store products and add them to a named collection (e.g., "My Tech Setup" or "Summer Favorites"). +- **Unique Collection Pages**: Each collection gets a dedicated, shareable URL (e.g., `/collection/my-tech-setup`). +- **Automatic Tracking**: When a customer buys any product from a collection page, the affiliate automatically earns commission. + +### Smart Links (Auto-Rotator) + +For affiliates running generic ads (like TikTok bio links or Facebook Ads), Smart Links maximize conversion by dynamically routing traffic. + +- **How it works**: A Smart Link uses the `/go/` prefix (e.g., `/go/my-tech-setup`). +- **Auto-Rotation**: When a customer clicks a Smart Link, the system instantly picks one product at random from the associated collection and redirects the user directly to that product's page. +- **Zero Friction**: The redirect happens server-side via a 302 redirect, ensuring the referral tracking cookie is set before the customer even sees the product page. + +## Admin Features + +### Affiliate Management + +- **View all affiliates**: Go to Admin > Marketing > Affiliates +- **Approve pending applications**: Click "Approve" button for pending affiliates +- **Edit custom rates**: Click pencil icon in the Rate column +- **Monitor earnings**: View Total Earnings and Payable Balance columns + +### Referral Monitoring + +- **View all referrals**: Admin > Marketing > Affiliates > Referrals tab +- **Filter by affiliate**: Select affiliate from dropdown +- **Filter by status**: pending, approved, rejected +- **Filter by date range**: Custom date filtering + +### Payout Management + +- **Create payouts**: Admin > Marketing > Affiliates > Payouts tab +- **Payment methods**: Bank Transfer or Store Credit +- **Store credit**: Automatically generates coupon code for affiliate + +## Customer Dashboard + +Affiliates can access their dashboard from **My Account > Affiliate Program**: + +- **Referral link**: Unique URL with their code (e.g., `/shop?ref=ABC123`) +- **Link Builder**: Tool to generate referral links to specific products or pages. +- **My Collections & Smart Links**: Tool to curate product collections and get auto-rotating Smart Links. +- **Statistics**: Total earnings, pending earnings, commission rate +- **Referral history**: List of all conversions with status +- **Payout history**: Record of past payments +- **Payment details**: Bank account information for receiving payouts + +## Configuration Options + +| Setting | Location | Description | Default | +|---------|----------|-------------|---------| +| Default Commission Rate | Affiliate Module Settings | Global fallback rate | 10% | +| Cookie Duration | Affiliate Module Settings | Days referral cookie is valid | 30 days | +| Self-Referral | Affiliate Module Settings | Allow affiliates to refer themselves | Disabled | +| Auto-Approve | Affiliate Module Settings | Automatically approve new applications | Disabled | +| Holding Period | Affiliate Module Settings | Days before commission becomes payable | 14 days | +| Enable Curated Collections | Affiliate Module Settings | Allow affiliates to create and share product collections | Enabled | + +## Commission Status Lifecycle + +``` +pending → approved → paid + ↓ ↓ +rejected (if refund/issue) +``` + +1. **Pending**: Commission recorded but held (14 days for refund protection) +2. **Approved**: Commission released and payable +3. **Paid**: Payout processed to affiliate +4. **Rejected**: Commission cancelled (order refunded or issue detected) \ No newline at end of file