# HubSpot Integration Setup Summary

**Last Updated:** 2026-02-12  
**Status:** ✅ Complete and Verified

## Important: Lead vs Deal Attribution

**Partners refer Ordio users (leads/customers), not partner dashboard users.**

- **Leads (Contacts):** Automatically tracked when users submit forms (demo booking, lead capture, etc.)
- **Deals:** Created by sales team when leads convert to customers. Sales must manually set affiliate properties on deals for MRR tracking.

See [HUBSPOT_SALES_WORKFLOW.md](HUBSPOT_SALES_WORKFLOW.md) for sales team guide on attributing deals to partners.

**Partner UTM and traffic source:** Partner-referred leads use the **same** UTM and traffic source properties as other leads (e.g. `source__c`, `utm_medium__c`, `utm_campaign__c`). Partner identity is stored in `affiliate_partner_id` (and `affiliate_referral_date`); separation in reports is by value (e.g. filter by `affiliate_partner_id` or `utm_source=affiliate`). See [PARTNER_UTM_AND_ATTRIBUTION.md](PARTNER_UTM_AND_ATTRIBUTION.md) for details.

## Setup Completion Status

### ✅ All Components Created

1. **Custom Object:** `affiliate_partner` (Object Type ID: `2-197867933`)
2. **Contact Properties:**
   - `affiliate_partner_id` (text)
   - `affiliate_referral_date` (date)
3. **Deal Properties:**
   - `affiliate_partner_id` (text)
   - `affiliate_mrr` (number)
   - `affiliate_subscription_status` (enum: active/paused/cancelled)
4. **Property Group:** `affiliate_info` (exists for contacts)
5. **API Scopes:** All required scopes verified

## Verification Results

### Comprehensive Verification: ✅ PASSED

```bash
php v2/scripts/hubspot/verify-affiliate-setup.php
```

**Results:**

- ✅ API Token: Valid and connected
- ✅ Custom Object: Exists with all properties
- ✅ Contact Properties: All exist
- ✅ Deal Properties: All exist
- ✅ Scopes: All required scopes present
- ✅ End-to-End Test: Partner creation/read/delete works

**Overall Status:** PASS (15/15 checks passed)

## Integration Tests

### Partner Registration Flow: ✅ PASSED

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

- ✅ Partner creation in HubSpot works
- ✅ All properties set correctly
- ✅ Object appears in HubSpot (after indexing)

### Sync Process: ✅ PASSED

```bash
php v2/cron/sync-affiliate-hubspot.php
```

- ✅ Sync completes successfully
- ✅ Fetches partner data from HubSpot
- ✅ Searches for contacts and deals
- ✅ Calculates MRR
- ✅ Updates cache file

### Lead Attribution: ✅ PASSED

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

- ✅ Contact creation with affiliate properties works
- ✅ Deal creation with affiliate properties works
- ✅ Properties are set correctly
- ⚠️ Search indexing is asynchronous (expected behavior)

## Configuration Updates

### Object Type ID Updated

The custom object was created with Object Type ID `2-197867933` (different from initial config).

**Updated in:** `v2/config/affiliate-config.php`

```php
define('HUBSPOT_AFFILIATE_OBJECT_TYPE', '2-197867933');
```

## Code Fixes Applied

### 1. Date Format Fix

HubSpot date properties require `YYYY-MM-DD` format (midnight UTC), not ISO 8601 timestamps.

**Fixed in:**

- `v2/helpers/hubspot-affiliate-api.php` - Added `formatHubSpotDate()` helper
- `v2/api/lead-capture.php` - Updated date format
- `v2/scripts/hubspot/test-affiliate-integration.php` - Updated date format

### 2. Property Creation Endpoint Fix

Changed from POST to `/crm/v3/properties/{objectType}/{propertyName}` to POST to `/crm/v3/properties/{objectType}` (property name in body).

**Fixed in:** `v2/scripts/hubspot/setup-affiliate-properties.php`

### 3. Partner Search Function Fix

Updated to search by `partner_id` property directly instead of trying object ID first.

**Fixed in:** `v2/helpers/hubspot-affiliate-api.php`

### 4. Deal Stage ID Fix

Updated test scripts to use actual pipeline stage ID instead of string `'closedwon'`.

**Fixed in:** `v2/scripts/hubspot/test-affiliate-integration.php`

## Known Behaviors

### Search Indexing Delay

HubSpot's search index updates asynchronously. Newly created records may not appear in search results immediately. This is expected and won't affect production because:

1. The sync process runs hourly (not real-time)
2. Records are created successfully (verified)
3. Search will find them after indexing completes (usually within minutes)

### Property Group for Deals

Deal properties were created in the default group (`dealinformation`) because `affiliate_info` group doesn't exist for deals yet. This doesn't affect functionality - properties can be moved to the correct group in HubSpot UI if desired.

## Production Readiness

### ✅ Ready for Production

All core functionality is working:

- Partner registration creates HubSpot objects ✅
- Contact/deal creation with affiliate properties ✅
- Sync process fetches and processes data ✅
- MRR calculation works ✅
- Level calculation works ✅

### Recommended Next Steps

1. **Monitor Sync Process:**
   - Set up hourly cron job: `0 * * * * php /path/to/v2/cron/sync-affiliate-hubspot.php`
   - Monitor logs for errors
   - Run health check: `php v2/scripts/affiliate/monitor-sync-health.php`

2. **Optional: Move Deal Properties to Group**
   - Go to HubSpot Settings → Properties → Deal Properties
   - Edit each affiliate property
   - Move to `affiliate_info` group (if group exists for deals)

3. **Test Real Registration:**
   - Register a test partner via the registration form
   - Verify HubSpot object is created
   - Check properties are set correctly

4. **Monitor Dashboard:**
   - Login to partner dashboard
   - Verify data displays correctly
   - Check that leads/deals appear after sync runs

## Verification Commands

```bash
# Full verification
php v2/scripts/hubspot/verify-affiliate-setup.php

# Test scopes
php v2/scripts/hubspot/test-api-token-scopes.php

# Test registration flow
php v2/scripts/hubspot/test-partner-registration.php

# Test sync process
php v2/cron/sync-affiliate-hubspot.php

# Test lead attribution
php v2/scripts/hubspot/test-lead-attribution.php

# End-to-end integration test
php v2/scripts/hubspot/test-affiliate-integration.php
```

## Related Documentation

- [HUBSPOT_INTEGRATION_TESTING_NOTION.md](HUBSPOT_INTEGRATION_TESTING_NOTION.md) – Sales-team overview of integration testing (for Notion import)
- [HUBSPOT_SETUP.md](HUBSPOT_SETUP.md) - Complete setup guide
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
- [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md) - Deployment checklist
- [HUBSPOT_SETUP_STATUS.md](HUBSPOT_SETUP_STATUS.md) - Setup status