# Partner Pages HubSpot Integration

**Last Updated:** 2026-01-29

Comprehensive guide to HubSpot integration for partner pages, including value mapping, synchronization, and troubleshooting.

## Overview

Partner attribution in HubSpot requires mapping partner slugs (from URL parameters) to HubSpot-accepted values. The `partner__c` field in HubSpot is an enumeration (dropdown) with specific accepted values that must match exactly.

## Architecture

### Data Flow

```
URL Parameter (partner=gastroberatung)
    ↓
Partner Config (gets hubspot_value)
    ↓
Mapping Function (mapPartnerToHubSpotValue)
    ↓
API Endpoint (sends mapped value)
    ↓
HubSpot Forms API v3
    ↓
HubSpot Contact (partner__c = "Gastro Beratung")
```

### Key Components

1. **Partner Configuration** (`v2/config/partner-config.php`)
   - Defines partner slugs, display names, and HubSpot values
   - Each partner includes `hubspot_value` field

2. **Mapping Helper** (`v2/config/partner-hubspot-mapping.php`)
   - Maps partner slugs to HubSpot-accepted values
   - Provides fallback formatting for unmapped partners

3. **API Endpoints**
   - All endpoints that send `partner__c` use mapping function
   - Logging tracks mapping transformations

4. **Sync Script** (`v2/scripts/hubspot/sync-partner-values.php`)
   - Fetches HubSpot property definition
   - Identifies missing partners
   - Can add missing values via API

5. **Test Script** (`v2/scripts/hubspot/test-partner-attribution.php`)
   - Validates partner mappings
   - Tests against HubSpot accepted values

## Partner Value Mapping

### How It Works

Partner slugs from URL parameters (e.g., `gastroberatung`) are automatically mapped to HubSpot-accepted values (e.g., `Gastro Beratung`) before being sent to HubSpot.

**Mapping Function:**

```php
$partnerSlug = $input['partner'] ?? ($_COOKIE['partner'] ?? '');
$partner = mapPartnerToHubSpotValue($partnerSlug);
```

**Partner Config:**

```php
'gastroberatung' => [
    'slug' => 'gastroberatung',
    'name' => 'Gastro Beratung',
    'hubspot_value' => 'Gastro Beratung', // Must match HubSpot exactly
    // ...
]
```

### Mapping Rules

1. **Primary**: Use `hubspot_value` field from partner config
2. **Fallback**: Use `name` field (display name) if `hubspot_value` not set
3. **Last Resort**: Format slug as display name (hyphens → spaces, capitalize)

### HubSpot Accepted Values

The `partner__c` field accepts specific enumeration values. Current accepted values include:

- `3POS`
- `Gastro Beratung`
- `Hitzel IT Solutions`
- `Kassenprofis`
- `MConsultings`
- `Paritätischer Gesamtverband`
- `Top Magazin`
- And more...

**Note**: Values are case-sensitive and must match exactly, including spaces and special characters.

## API Endpoints

All endpoints that send `partner__c` to HubSpot use the mapping function:

1. **`v2/api/collect-lead.php`** - Tools/calculator forms
2. **`v2/api/submit-template.php`** - Template download forms
3. **`v2/api/addon-request.php`** - Addon pricing inquiry forms

**Implementation Pattern:**

```php
// Include mapping helper
require_once __DIR__ . '/../config/partner-hubspot-mapping.php';

// Extract partner slug
$partnerSlug = $input['partner'] ?? ($_COOKIE['partner'] ?? '');

// Map to HubSpot value
$partner = mapPartnerToHubSpotValue($partnerSlug);

// Log mapping transformation
if (!empty($partnerSlug) && empty($partner)) {
    ordio_log('WARN', 'Partner slug has no HubSpot mapping', [
        'partner_slug' => $partnerSlug,
        'endpoint' => 'endpoint-name'
    ]);
} elseif (!empty($partnerSlug) && $partnerSlug !== $partner) {
    ordio_log('INFO', 'Partner slug mapped to HubSpot value', [
        'partner_slug' => $partnerSlug,
        'hubspot_value' => $partner,
        'endpoint' => 'endpoint-name'
    ]);
}

// Send to HubSpot
[
    "name" => "partner__c",
    "value" => $partner
]
```

## Adding New Partners

### Step 1: Add Partner Configuration

Edit `v2/config/partner-config.php`:

```php
'new-partner-slug' => [
    'slug' => 'new-partner-slug',
    'name' => 'New Partner Name',
    'hubspot_value' => 'New Partner Name', // Must match HubSpot value exactly
    'logo_path' => '/v2/img/partner/new-partner-slug.webp',
    'logo_class' => 'w-40',
    'special_pricing' => null,
],
```

### Step 2: Verify HubSpot Value Exists

Run sync script to check:

```bash
php v2/scripts/hubspot/sync-partner-values.php --dry-run
```

This will show if the value exists in HubSpot or needs to be added.

### Step 3: Add Value to HubSpot (if missing)

**Option A: Use API (requires permissions):**

```bash
php v2/scripts/hubspot/sync-partner-values.php --add-missing
```

**Option B: Add manually in HubSpot:**

1. Go to Settings → Properties → Contacts
2. Find `partner__c` property
3. Click "Edit"
4. Add new option with exact value from config
5. Save

### Step 4: Test Mapping

```bash
php v2/scripts/hubspot/test-partner-attribution.php new-partner-slug
```

This validates the mapping and confirms the value exists in HubSpot.

### Step 5: Test End-to-End

1. Test URL: `https://www.ordio.com/v2/?partner=new-partner-slug`
2. Submit form
3. Verify HubSpot contact has correct `partner__c` value

## Synchronization

### Sync Script Usage

**Dry Run (check only):**

```bash
php v2/scripts/hubspot/sync-partner-values.php --dry-run
```

**Add Missing Values:**

```bash
php v2/scripts/hubspot/sync-partner-values.php --add-missing
```

**What It Does:**

1. Fetches `partner__c` property definition from HubSpot
2. Compares with partner configuration
3. Identifies missing partners
4. Optionally adds missing values via API

### Manual Synchronization

If API doesn't have permissions to update properties:

1. Run sync script with `--dry-run` to see missing values
2. Add values manually in HubSpot UI
3. Re-run sync script to verify

## Testing

### Test Partner Attribution

**Test Single Partner:**

```bash
php v2/scripts/hubspot/test-partner-attribution.php gastroberatung
```

**Test All Partners:**

```bash
php v2/scripts/hubspot/test-partner-attribution.php
```

**What It Tests:**

- Partner exists in configuration
- Mapping function returns value
- Value exists in HubSpot accepted values
- Mapping is valid

### Manual Testing

1. **Test URL:**

   ```
   https://www.ordio.com/v2/?partner=gastroberatung&title=Gastro%20Beratung%20empfiehlt%20Ordio&leadSource=Partner%20recommendation
   ```

2. **Submit Form:**
   - Fill out form on partner landing page
   - Submit

3. **Verify in HubSpot:**
   - Find contact in HubSpot
   - Check `partner__c` field
   - Should show: `Gastro Beratung` (not `gastroberatung`)

## Troubleshooting

### Partner Value Not Appearing in HubSpot

**Symptoms:**

- `partner__c` field is empty or shows "--"
- Partner parameter present in URL
- Form submission includes partner parameter

**Diagnosis:**

1. **Check Mapping:**

   ```bash
   php v2/scripts/hubspot/test-partner-attribution.php [partner-slug]
   ```

2. **Check Logs:**

   ```bash
   grep "Partner slug" v2/logs/*.log
   ```

3. **Check HubSpot Value Exists:**
   ```bash
   php v2/scripts/hubspot/sync-partner-values.php --dry-run
   ```

**Common Issues:**

1. **Value Mismatch**: Slug doesn't match HubSpot value
   - Fix: Update `hubspot_value` in partner config

2. **Missing Value**: Value doesn't exist in HubSpot
   - Fix: Add value to HubSpot manually or via API

3. **Mapping Not Applied**: API endpoint not using mapping function
   - Fix: Ensure endpoint includes mapping helper and uses `mapPartnerToHubSpotValue()`

### Mapping Warnings in Logs

**Warning: "Partner slug has no HubSpot mapping"**

- Partner slug not found in configuration
- Fix: Add partner to `partner-config.php`

**Info: "Partner slug mapped to HubSpot value"**

- Normal operation - slug successfully mapped
- No action needed

## Maintenance

### Periodic Sync Check

Run sync script monthly to ensure all partners are synced:

```bash
php v2/scripts/hubspot/sync-partner-values.php --dry-run
```

### Adding Multiple Partners

1. Add all partners to config with `hubspot_value` fields
2. Run sync script to identify missing values
3. Add missing values to HubSpot (manually or via API)
4. Run test script to validate all mappings

## Best Practices

1. **Always Include hubspot_value**: Set `hubspot_value` field when adding new partners
2. **Test Before Deploying**: Run test script before deploying new partners
3. **Sync Regularly**: Run sync script monthly to catch discrepancies
4. **Monitor Logs**: Check logs for mapping warnings
5. **Case Sensitivity**: HubSpot values are case-sensitive - match exactly
6. **Spaces Matter**: "Gastro Beratung" ≠ "GastroBeratung" - match exactly

## Related Documentation

- [Partner Pages Guide](./PARTNER_PAGES_GUIDE.md) - Complete partner pages documentation
- [Attribution Debugging Guide](../../development/ATTRIBUTION_DEBUGGING_GUIDE.md) - Attribution troubleshooting
- [HubSpot API Reference](../../systems/apis/HUBSPOT_API_REFERENCE.md) - HubSpot API documentation

## Support

For questions or issues with HubSpot integration:

1. Check this documentation
2. Run test script: `php v2/scripts/hubspot/test-partner-attribution.php`
3. Run sync script: `php v2/scripts/hubspot/sync-partner-values.php --dry-run`
4. Check logs: `grep "Partner" v2/logs/*.log`
5. Contact development team