# FINEART Referral Program

## 🎯 Quick Start

### What This Does
- Artists get unique referral links
- Sales from their links or embedded galleries earn **1.5x commission** (+50% bonus)
- Beautiful dashboard for tracking referrals and earnings
- Automatic tracking - zero maintenance required

---

## ⚡ 3-Minute Setup

### 1. Add to functions.php

Copy the entire content of:
```
includes/helpers/fineart-commission-integration.php
```

Paste it into your theme's `functions.php` file.

**OR** if you prefer, just add this single filter:

```php
add_filter('vendor_commission_amount', 'fineart_custom_commission_by_size', 99, 6);
function fineart_custom_commission_by_size($amount, $product_id, $variation_id, $item, $order_id, $item_id) {
    $size_to_commission = array(
        'SMALL'  => 30,
        'MEDIUM' => 60,
        'LARGE'  => 120,
        'LUXE'   => 240,
    );
    
    $commission = 0;
    foreach ($item->get_all_formatted_meta_data() as $meta) {
        $value = trim(strip_tags(wp_kses_post($meta->display_value)));
        if (array_key_exists($value, $size_to_commission)) {
            $commission = $size_to_commission[$value];
            break;
        }
    }
    
    if ($commission == 0) $commission = $amount;
    
    // Apply 1.5x bonus for artist-driven sales
    $order = wc_get_order($order_id);
    if ($order) {
        $ref_vendor_id = $order->get_meta('_fineart_artist_ref_vendor');
        $product_vendor_id = get_post_field('post_author', $product_id);
        
        if ($ref_vendor_id && $ref_vendor_id == $product_vendor_id) {
            $commission = $commission * 1.5;
        }
    }
    
    return $commission;
}
```

### 2. Flush Permalinks

1. Go to **Settings > Permalinks**
2. Click **Save Changes**

### 3. Done! 🎉

Artists can now access their referral dashboard at:
```
https://fineart.gallery/vendor-dashboard/referral-program
```

---

## 📊 How It Works

### For Artists

**Get Referral Link:**
```
https://fineart.gallery/?ref=artistname
```

**Register Website:**
```
https://myartistwebsite.com
```

**Share & Earn:**
- Social media posts
- Email campaigns  
- Website embedding
- Newsletter links

### Commission Examples

| Print Size | Normal | With Referral | Bonus |
|-----------|--------|---------------|-------|
| SMALL     | €30    | €45          | +€15  |
| MEDIUM    | €60    | €90          | +€30  |
| LARGE     | €120   | €180         | +€60  |
| LUXE      | €240   | €360         | +€120 |

---

## 🎨 Features

✅ **Unique Referral Links** - Each artist has their own  
✅ **Embedded Gallery Tracking** - Automatic domain detection  
✅ **90-Day Cookie Tracking** - Long attribution window  
✅ **Self-Purchase Support** - Artists can buy their own work  
✅ **Beautiful Dashboard** - Stats, links, and management  
✅ **Order Notes** - Clear tracking of referral sales  
✅ **Zero Maintenance** - Set it and forget it  

---

## 📱 Dashboard Preview

The referral dashboard shows:
- Copyable referral link
- Domain registration form
- Sales statistics
- Earnings tracker
- How-it-works guide
- FAQ section

---

## 🔗 Integration Points

### Works With:
- ✅ WooCommerce orders
- ✅ WC Vendors / MultivendorX
- ✅ Existing embed gallery system
- ✅ Current commission structure
- ✅ All payment gateways

### Tracking Sources:
1. **Referral Links** - `?ref=username` parameter
2. **Embedded Galleries** - HTTP referer detection
3. **Direct Links** - Product pages with artist context

---

## 🛠️ Configuration

### Change Commission Multiplier

In `class-fineart-referral-system.php` line ~225:
```php
$amount = $amount * 1.5;  // Change to 2.0 for double commission
```

### Change Tracking Duration

In `class-fineart-referral-system.php` line ~117:
```php
time() + (90 * DAY_IN_SECONDS),  // Change 90 to desired days
```

### Add to Dashboard Menu

The endpoint auto-registers. If needed, add menu item:
```php
array(
    'label' => 'Referral Program',
    'url' => home_url('/vendor-dashboard/referral-program'),
    'icon' => 'dashicons-awards',
)
```

---

## 🐛 Troubleshooting

**404 on dashboard page:**
- Settings > Permalinks > Save Changes

**Referral not tracking:**
- Check cookies enabled
- Test in incognito mode
- Verify no cookie blockers

**Commission not applying:**
- Check functions.php has the filter
- Look for order notes on test orders
- Verify product has correct vendor

**Embed not tracking:**
- Domain must be registered
- Must come from external domain
- Check HTTP_REFERER is sent

---

## 📖 Full Documentation

See `REFERRAL-PROGRAM-SETUP.md` for complete documentation including:
- Detailed installation guide
- Security notes
- Advanced customization
- Testing checklist
- API reference

---

## 📞 Support

**Installation Issues:**
1. Verify all files uploaded correctly
2. Check functions.php syntax
3. Review WordPress error logs
4. Test in incognito mode

**Feature Requests:**
Contact FINEART development team

---

## 🎯 Key Files

```
fineart-plugin/
├── includes/
│   └── class-fineart-referral-system.php    ← Core logic
├── templates/vendor-dashboard/
│   └── referral-program.php                  ← Dashboard UI
├── css/
│   └── referral-program.css                  ← Styles
└── includes/helpers/
    └── fineart-commission-integration.php    ← functions.php code
```

---

## 🚀 Launch Checklist

Before announcing to artists:

- [ ] Commission filter added to functions.php
- [ ] Permalinks flushed
- [ ] Test referral link creates cookie
- [ ] Test purchase with referral applies bonus
- [ ] Test domain registration saves correctly
- [ ] Test embedded gallery tracking from external site
- [ ] Review dashboard looks good on mobile
- [ ] Create announcement/tutorial for artists

---

## 💡 Marketing Ideas

**Announce to Artists:**
```
🎉 New Feature: Earn 50% More Commission!

Share your unique referral link and earn 1.5x commission 
on every sale you bring. The more you promote, the more 
you earn!

Get started: [Dashboard Link]
```

**Email Template:**
```
Subject: 💰 Boost Your Earnings with Our New Referral Program

Hi [Artist Name],

Great news! You can now earn 50% MORE commission when you 
bring your own sales through:

✨ Your unique referral link
✨ Your embedded gallery  
✨ Your social media promotions

Example: Instead of €120 for a LARGE print, you'll earn €180!

Get your referral link: [Dashboard Link]

Happy selling!
```

---

## 🎊 Success Metrics

Track these KPIs:
- Number of artists using referral links
- Percentage of sales from referrals
- Average bonus per artist
- Conversion rate of referral traffic
- Top performing referral sources

---

Made with ❤️ for FINEART artists
Version 1.0 | Updated February 2026