Data Sync

This page explains how data flows between HubSpot, the integration backend, and QuickBooks Online.

Overview

Data flow direction: HubSpot → Integration → QuickBooks (primarily one-way)

When sync occurs: During invoice creation (not continuous background sync)

Data synced:

• HubSpot contacts → QuickBooks customers
• HubSpot deal data → QuickBooks invoice details
• Integration configuration → Encrypted database storage

Contact to Customer Sync

Sync Trigger

Triggered by: Creating an invoice from a deal

Process:

1. User selects contact when creating invoice
2. Integration searches QuickBooks for customer by email
3. If found: Uses existing customer
4. If not found: Creates new customer

Frequency: On-demand only (not automatic background sync)

Data Mapped

Display Name: [First Name] [Last Name]

Matching Logic

Primary match field: Email address

Match criteria:

• Case-insensitive email comparison
• Exact match required
• Whitespace trimmed

If match found: Uses existing customer (no update)

If no match: Creates new customer

See Customer Sync

Deal to Invoice Sync

Data Mapped

Calculation:

• Deposit: Deal Amount × Percentage
• Follow-up: Deal Amount × Percentage
• Final: Deal Amount × Percentage (or remaining)

What’s NOT Synced

❌ Not synced from deal:

• Deal stage
• Deal owner
• Custom deal properties
• Deal notes
• Associations (except primary contact)

Integration Configuration Sync

Stored Data

Encrypted storage:

• Client ID and Secret
• OAuth access token
• OAuth refresh token
• QuickBooks Realm ID

Unencrypted storage:

• Default tax code ID
• Default product ID
• Environment selection
• HubSpot account ID

Encryption: AES-256-GCM with PBKDF2-derived keys

See Data Sharing

Sync Direction

HubSpot → QuickBooks

✅ Synced:

• Contact information (name, email, phone, address)
• Deal amount
• Deal name
• Line items (if used)
• Quote data (if applicable)

❌ Not synced:

• Custom properties
• Deal stage
• Contact notes
• Deal activities

QuickBooks → HubSpot

❌ Not synced back:

• Payment status
• Invoice edits
• Customer updates
• Balance changes

Reason: Read-only OAuth scopes for HubSpot; integration cannot write to HubSpot CRM

Real-Time vs Batch

Real-time (immediate):

• Invoice creation
• Customer creation/lookup
• OAuth token exchange

Not supported:

• Batch invoice creation
• Bulk customer sync
• Scheduled background sync

Data Freshness

Contact Data

Sync timing: At invoice creation

Staleness: If contact data changes in HubSpot after customer created, QuickBooks customer does NOT auto-update

Update method: Manual update in QuickBooks

Deal Data

Sync timing: At each invoice creation

Current data: Uses deal amount at time of invoice creation

Example: If deal amount changes from $5,000 to $6,000, next invoice will use $6,000

Sync Failures

Customer Creation Failure

Causes:

• Invalid email format
• Missing required fields
• QuickBooks API error

Handling: Error displayed to user, invoice not created

Invoice Creation Failure

Causes:

• Customer creation failed
• Invalid invoice data
• QuickBooks API error
• Network timeout

Handling: Error displayed, invoice not created, customer may have been created

Data Consistency

Ensuring Consistency

✅ Do:

• Keep contact emails accurate
• Update both systems if changes needed
• Use QuickBooks as source of truth for customer data after creation
• Use HubSpot as source of truth for deal data

❌ Don’t:

• Expect automatic bi-directional sync
• Change emails frequently
• Assume updates sync automatically

Handling Discrepancies

If HubSpot and QuickBooks differ:

1. Determine which system has correct data
2. Update the other system manually
3. Document the source of truth

Privacy and Security

Data Transience

Temporary data (not stored):

• Contact details during sync
• Deal data during invoice creation
• Invoice details in transit

Data flows through backend but is not persisted

Encrypted Data

Permanently stored (encrypted):

• OAuth credentials
• Access/refresh tokens

Deleted upon:

• Disconnection
• Uninstallation

See Data Impact

Sync Limitations

What Cannot Be Synced

❌ Technical limitations:

• Custom contact properties (not in standard sync fields)
• Deal custom properties
• HubSpot timeline events
• Contact notes and activities
• File attachments

❌ Scope limitations:

• Cannot write to HubSpot (read-only scopes)
• Cannot modify existing QuickBooks customers
• Cannot update QuickBooks invoices from HubSpot

Workarounds

For payment status sync:

• Manual: Create custom deal property, update manually
• Automation: Use third-party integration tools (Zapier, Make)
• Workflow: Train team to update HubSpot after QB payment

For custom properties:

• Use standard fields when possible
• Manual data entry where needed
• Custom integration development

Future Enhancements

Potential future features (not currently available):

• Bi-directional sync
• Payment status sync to HubSpot
• Custom field mapping
• Scheduled background sync
• Webhook-based updates

Request features: Contact support

Best Practices

✅ Do:

• Verify data accuracy before creating invoices
• Keep contact information current
• Use consistent data formats
• Document which system is source of truth
• Train team on sync behavior

❌ Don’t:

• Expect automatic synchronization
• Change data in one system and assume it updates elsewhere
• Use outdated contact information
• Create duplicate customers

Additional Resources

• Customer Sync - Detailed sync process
• Data Sharing - Complete data flow documentation
• Creating Invoices - How sync occurs during invoice creation
• OAuth Scopes - What data can be accessed