# Partner UTM Parameters & Attribution

**Last Updated:** 2026-04-10

**Stakeholder summary:** Partners can keep customizing UTMs; attribution is still by affiliate ID; we documented best practices and recommend source=affiliate, medium=referral; no HubSpot changes required.

How partner referral links interact with UTM parameters and HubSpot attribution. Use this when configuring or documenting the referral URL generator, lead capture, or HubSpot properties.

## Summary

- **Partner attribution (commission/identity):** Stored in HubSpot as `affiliate_partner_id` (and `affiliate_referral_date`). Source of truth is the `affiliate` query parameter and cookie, **not** UTM values.
- **Campaign/channel (analytics):** Partner links can include UTM parameters; they use the **same** HubSpot UTM/traffic source properties as the rest of the site (`source__c`, `utm_medium__c`, `utm_campaign__c`, etc.).
- **Separation:** Partner traffic is distinguished by **values** (e.g. `utm_source=affiliate` or `partner`), not by separate HubSpot properties.
- **Best practice:** Do **not** create separate HubSpot UTM properties for partners. Use the same properties and filter partner traffic by `utm_source` or `affiliate_partner_id`.

## Partner Attribution vs UTM

| Purpose | Stored where | Source |
|--------|----------------|--------|
| **Who** (partner identity, commission) | `affiliate_partner_id`, `affiliate_referral_date` on contact/deal | `affiliate` query param and cookie |
| **What** (campaign, medium, content) | Same UTM properties as other traffic (`source__c`, `utm_medium__c`, etc.) | UTM query params and cookies |

Partner UTMs do **not** override or replace partner attribution. They add campaign-level detail on top of `affiliate_partner_id`.

## Recommended Partner UTM Values

- **utm_source:** `affiliate` or `partner` (identifies the channel as partner referral).
- **utm_medium:** `referral`, or sub-type such as `email`, `social` (how the link was shared).
- **utm_campaign:** Offer or promo name (e.g. `january2026`, `blog-artikel`).
- **utm_content** / **utm_term:** Optional, for granularity (e.g. banner variant, keyword).

Using these values keeps partner traffic easy to filter in reports and avoids polluting organic/paid source buckets (e.g. avoid `utm_source=google` or `utm_medium=organic` for partner links).

## HubSpot: Same Properties for All Traffic

Partner leads use the **same** UTM and traffic source properties as other leads. Partner identity is stored in:

- **Contacts:** `affiliate_partner_id`, `affiliate_referral_date`
- **Deals:** `affiliate_partner_id` (set by sales when attributing a deal to a partner)

UTM data (source, medium, campaign, term, content) is stored in the same custom properties used for non-partner traffic. Filter partner reports by `affiliate_partner_id` or by UTM values (e.g. `utm_source=affiliate`).

## Original and Latest Traffic Source (HubSpot)

HubSpot’s **Original** and **Latest** traffic source properties are set automatically from contact interactions. Depending on UTM values, partner traffic may be classified under “Referral” or “Other Campaigns.” For reliable partner reporting, filter by:

- `affiliate_partner_id` (presence or specific partner ID), or
- Custom UTM properties (e.g. `source__c` = `affiliate` or `partner`)

 rather than relying only on Original/Latest traffic source labels.

## Reporting in Partner Dashboard

UTM data is exposed in the partner dashboard for campaign comparison:

- **Leads API** (`/v2/api/affiliate-leads.php`): Each lead includes optional `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` (null when not set).
- **Leads page** (`/partner/leads`): Quelle, Medium, Kampagne columns in the leads table; "Lead-Quellen" card with three interactive horizontal bar charts (Quelle, Medium, Kampagne) in a 3-column grid when at least one lead has UTM data.
- **Dashboard** ("Letzte Aktivitäten"): UTM badge shown next to each lead (campaign when set; otherwise source / medium when either exists).
- **No UTM data:** When no leads have UTM parameters, a hint card encourages partners to use UTMs with a link to Referral-URLs.

## Conflict Risk and Mitigation

If a partner sets values like `utm_source=google` or `utm_medium=organic`, organic/paid reports can be polluted. Mitigation:

- **Recommend** in the referral UI and docs: use `utm_source` = affiliate/partner and `utm_medium` = referral (or email/social).
- Optionally add a **soft** client-side warning (no block) when non-partner-like values are used.

## Form Coverage Matrix (Ordio Loop affiliate_partner_id)

All forms that submit to HubSpot must capture the `affiliate` param and send `affiliate_partner_id` for Ordio Loop commission attribution.

| Form/Endpoint | affiliate_partner_id | partner__c | Notes |
|---------------|----------------------|------------|-------|
| form-hs.php | ✓ | ✓ | Main demo, SDR, gated content, webinar, event |
| collect-lead.php | ✓ | ✓ | Tools/calculators |
| lead-capture.php | ✓ | — | Lead capture popup |
| submit-template.php | ✓ | ✓ | Template downloads |
| addon-request.php | ✓ | ✓ | Add-on pricing |
| export-workdays.php | ✓ | — | Workdays export |
| shiftops-hubspot.php | ✓ | — | ShiftOps report |
| include_email_form.php | ✓ | ✓ | Hero email, Cello |
| include_form-hubspot-sdr.php | ✓ | — | HubSpot embedded SDR |
| affiliate-partner-refer-lead.php | ✓ | — | Partner session → `affiliate_partner_id`; fixed `source__c`/`utm_*` for partner refer channel |

**Extraction priority:** POST field (affiliate_modal/affiliate) → cookie → page_url query param.

For **affiliate-partner-refer-lead.php**, the partner is taken from the authenticated session (not URL/cookie).

See [FORM_REFERRAL_CAPTURE_AUDIT.md](FORM_REFERRAL_CAPTURE_AUDIT.md) for audit details.

## Verification (manual test)

To confirm partner attribution and UTM both reach HubSpot:

1. Open a partner referral URL with custom UTMs, e.g. `https://www.ordio.com/?affiliate=AP-TEST&utm_source=partner&utm_medium=referral&utm_campaign=test-campaign`.
2. Submit a lead-capture form on the site (e.g. demo request or lead capture).
3. In HubSpot, open the created contact and verify: `affiliate_partner_id` is set (e.g. AP-TEST) and UTM properties (e.g. source__c, utm_medium__c, utm_campaign__c) match the URL.

## Related Documentation

- [REFERRAL_PAGE_GUIDE.md](REFERRAL_PAGE_GUIDE.md) – Referral page and UTM generator
- [HUBSPOT_INTEGRATION_SUMMARY.md](HUBSPOT_INTEGRATION_SUMMARY.md) – HubSpot setup and lead/deal attribution
- [PARTNER_GUIDE.md](PARTNER_GUIDE.md) – User-facing partner guide