# HubSpot Sales Workflow for Affiliate Attribution

**Last Updated:** 2026-02-12

Guide for sales team on how to attribute deals to affiliate partners in HubSpot.

## Overview

When a partner refers someone who becomes an Ordio customer:

1. **Lead is automatically tracked** - When the referred user submits a form (demo booking, lead capture, etc.), the contact is automatically tagged with `affiliate_partner_id`
2. **Sales creates deal** - Sales team creates deals in HubSpot when leads convert to customers
3. **Sales sets affiliate properties** - Sales team manually sets affiliate properties on the deal to enable MRR tracking and partner earnings

## Lead Attribution (Automatic)

### How It Works

1. Partner shares referral link: `https://www.ordio.com/?affiliate=AP-20260129-ABC123`
2. User clicks link and browses the site
3. User submits a form (lead capture, demo booking, etc.)
4. **System automatically sets:**
   - `affiliate_partner_id` = Partner ID (e.g., `AP-20260129-ABC123`)
   - `affiliate_referral_date` = Date of form submission

### Where to See Attributed Leads

In HubSpot:

1. Go to Contacts
2. Filter by property: `Affiliate Partner ID` is not empty
3. Or search for specific partner ID: `affiliate_partner_id:AP-20260129-ABC123`

## Deal Attribution (Manual - Sales Team)

### When to Set Affiliate Properties

When creating or updating a deal for a customer who was referred by an affiliate partner:

1. **Check if contact has affiliate attribution:**
   - Open the contact record
   - Look for `Affiliate Partner ID` property
   - If present, note the Partner ID

2. **When creating a new deal:**
   - Create deal as usual
   - Link deal to the contact
   - Set affiliate properties (see below)

3. **When updating an existing deal:**
   - Open the deal
   - Check if contact has `Affiliate Partner ID`
   - If yes, set affiliate properties on the deal

### How to Set Affiliate Properties on Deals

**Option 1: Manual Entry in HubSpot UI**

1. Open the deal in HubSpot
2. Scroll to "Affiliate Info" property group (or "Deal Information" if group doesn't exist)
3. Set these properties:
   - **Affiliate Partner ID:** Enter the Partner ID (e.g., `AP-20260129-ABC123`)
   - **Affiliate MRR:** Enter the monthly recurring revenue amount (e.g., `89` for €89/month)
   - **Affiliate Subscription Status:** Select `Active`, `Paused`, or `Cancelled`

**Option 2: Use HubSpot Workflow (Recommended)**

Create a HubSpot workflow that automatically copies `affiliate_partner_id` from contact to deal:

1. Go to HubSpot Settings → Automation → Workflows
2. Create new workflow: "Copy Affiliate Attribution to Deal"
3. Trigger: When deal is created or updated
4. Action: Copy contact property `affiliate_partner_id` to deal property `affiliate_partner_id`
5. (Optional) Set default MRR and status

**Option 3: Bulk Update via API (For Admins)**

Use the helper function to update deals programmatically:

```php
require_once 'v2/helpers/hubspot-affiliate-api.php';

updateDealWithAffiliatePartner(
    $dealId,           // HubSpot deal ID
    $partnerId,        // Partner ID (e.g., 'AP-20260129-ABC123')
    $mrr,              // Monthly recurring revenue (e.g., 89)
    'active'           // Subscription status
);
```

## Property Details

### Contact Properties (Set Automatically)

- **`affiliate_partner_id`** (text)
  - Partner ID who referred this contact
  - Set automatically when form is submitted with affiliate parameter
- **`affiliate_referral_date`** (date)
  - Date when contact was referred
  - Set automatically when form is submitted

### Deal Properties (Set by Sales)

- **`affiliate_partner_id`** (text)
  - Partner ID who referred this deal
  - **Required for MRR calculation**
  - Copy from contact's `affiliate_partner_id` property
- **`affiliate_mrr`** (number)
  - Monthly recurring revenue for this deal
  - **Required for MRR calculation**
  - Enter the actual MRR amount (e.g., `89` for €89/month)
- **`affiliate_subscription_status`** (enum)
  - Current subscription status
  - Options: `Active`, `Paused`, `Cancelled`
  - **Required for MRR calculation**
  - Default: `Active`

## MRR Calculation

Partner earnings are calculated based on deals with affiliate properties:

```
Partner MRR = Σ(Deal MRR × Partner Level MRR Share %)
```

**Partner Level MRR Shares:**

- Starter (1–5 deals in 90 days): 20% of deal MRR
- Partner (6–10 deals in 90 days): 25% of deal MRR
- Pro (11+ deals in 90 days): 30% of deal MRR

**Example:**

- Deal MRR: €89/month
- Partner Level: Partner (25% share)
- Partner Earnings: €89 × 25% = €22.25/month

## Best Practices

### For Sales Team

1. **Always check contact attribution** before creating deals
2. **Set affiliate properties immediately** when creating deals for referred customers
3. **Update subscription status** when customers pause or cancel
4. **Set accurate MRR** - Use actual monthly subscription amount
5. **Verify attribution** - Check partner dashboard shows the deal after sync runs

### For Admins

1. **Set up HubSpot workflow** to automate affiliate property copying
2. **Train sales team** on manual attribution process
3. **Monitor sync process** to ensure deals are being tracked
4. **Review partner dashboard** regularly to verify data accuracy

## Troubleshooting

### Deal Not Showing in Partner Dashboard

**Check:**

1. Is `affiliate_partner_id` set on the deal?
2. Is `affiliate_mrr` set on the deal?
3. Is deal stage "Closed Won"?
4. Has sync process run since deal was created/updated?

**Fix:**

1. Set missing properties on the deal
2. Wait for next sync (runs hourly)
3. Or trigger manual sync: `php v2/cron/sync-affiliate-hubspot.php`

### MRR Calculation Incorrect

**Check:**

1. Is `affiliate_mrr` property set correctly?
2. Is `affiliate_subscription_status` set correctly?
3. Is partner level correct (affects MRR share percentage)?

**Fix:**

1. Update deal properties with correct values
2. Wait for sync to recalculate MRR

### Contact Has Affiliate ID But Deal Doesn't

**Cause:** Sales didn't set affiliate properties when creating deal.

**Fix:**

1. Open the deal in HubSpot
2. Copy `affiliate_partner_id` from contact
3. Set all three affiliate properties on the deal
4. Wait for sync to update partner dashboard

## Automation Options

### HubSpot Workflow (Recommended)

Create a workflow that automatically sets affiliate properties on deals:

**Trigger:** Deal created or updated

**Conditions:**

- Associated contact has `affiliate_partner_id` property set
- Deal stage is "Closed Won"

**Actions:**

1. Copy `affiliate_partner_id` from contact to deal
2. Set `affiliate_mrr` = Deal amount (or custom field)
3. Set `affiliate_subscription_status` = "Active"

### HubSpot Custom Action

Create a custom action button in HubSpot that:

1. Reads `affiliate_partner_id` from associated contact
2. Sets all three affiliate properties on the deal
3. Prompts for MRR amount if not set

## Related Documentation

- [HUBSPOT_WORKFLOW_TEMPLATE.md](HUBSPOT_WORKFLOW_TEMPLATE.md) - Automated workflow setup guide
- [HUBSPOT_SETUP.md](HUBSPOT_SETUP.md) - Technical setup guide
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
- [PARTNER_GUIDE.md](PARTNER_GUIDE.md) - Partner user guide