HubSpot + QuickBooks Integration Guide

This guide walks you through setting up a complete integration between HubSpot and QuickBooks Online. By the end, your CRM contacts will sync with your accounting system's customer records.

Overview

Goal: Keep HubSpot Contacts and Companies in sync with QuickBooks Online Customers, so your sales and accounting teams share consistent customer data.

What You'll Set Up:

• HubSpot Contacts synced with QuickBooks Customers
• HubSpot Companies synced with QuickBooks Customers (business type)
• Name and address field mapping
• One-way vs. bidirectional considerations for accounting data

Time Required: 15–20 minutes

Prerequisites

Before starting, ensure you have:

• [ ] A FluxCascade account (sign up free)
• [ ] Admin access to your HubSpot portal
• [ ] Admin access to your QuickBooks Online account
• [ ] Both platforms connected to FluxCascade

If you haven't connected your platforms yet, follow the HubSpot integration docs first. For QuickBooks, go to Connections → Add Connection → QuickBooks Online and authorize via OAuth.

Step 1: Understand the Data Model Differences

HubSpot and QuickBooks organize customer data differently:

• HubSpot separates people (Contacts) from companies (Companies). A Contact can be associated with a Company.
• QuickBooks Online has a single Customer object. A Customer can represent an individual or a business. Sub-customers can nest under a parent customer.

You'll typically create two mappings: one for HubSpot Contacts → QuickBooks individual Customers, and one for HubSpot Companies → QuickBooks business Customers.

Step 2: Plan Your Contact → Customer Mapping

Contact Field Pairs

QuickBooks DisplayName

QuickBooks requires a DisplayName field, which must be unique across all customers. FluxCascade auto-generates this by concatenating first and last name. If you need a custom format, use a concatenate transform:

{firstname} {lastname}

Or for business customers:

{company}

Step 3: Create the Contact → Customer Mapping

1. Go to Mappings in FluxCascade
2. Click New Mapping
3. Configure the basics:

Source:

• Connection: Your HubSpot connection
• Object: Contacts

Target:

• Connection: Your QuickBooks connection
• Object: Customers

Direction: HubSpot → QuickBooks (one-way recommended — see below)

4. Click Continue

One-Way vs. Bidirectional

For most HubSpot + QuickBooks setups, one-way sync (HubSpot → QuickBooks) is recommended:

• HubSpot is typically the system of record for contact information
• QuickBooks Customers are created when a deal closes or an invoice is needed
• Editing customer records in QuickBooks for accounting purposes shouldn't overwrite CRM data

If your accounting team also updates contact info (addresses, phone numbers), consider bidirectional sync with QuickBooks winning on address fields.

Step 4: Configure Field Pairs

Add these field pairs:

1. First Name

   • Source: firstname
   • Target: GivenName
   • Transform: None

2. Last Name

   • Source: lastname
   • Target: FamilyName
   • Transform: None

3. Email (Matching Field)

   • Source: email
   • Target: PrimaryEmailAddr.Address
   • Transform: lowercase
   • Mark as Matching Field

4. Phone

   • Source: phone
   • Target: PrimaryPhone.FreeFormNumber
   • Transform: phone_e164

5. Company

   • Source: company
   • Target: CompanyName
   • Transform: None

Address Fields

6. Street

   • Source: address
   • Target: BillAddr.Line1

7. City

   • Source: city
   • Target: BillAddr.City

8. State

   • Source: state
   • Target: BillAddr.CountrySubDivisionCode

9. Postal Code

   • Source: zip
   • Target: BillAddr.PostalCode

Step 5: Company → Customer Mapping (Optional)

To sync HubSpot Companies as QuickBooks business-type Customers:

1. Create a second mapping: HubSpot Companies → QuickBooks Customers
2. Map the following:

Use CompanyName or domain as the matching field for Company → Customer sync.

Step 6: Handling Invoice Data

QuickBooks is primarily an accounting system, so invoice and payment data typically stays in QuickBooks. However, you may want to:

Sync invoice totals back to HubSpot (read-only):

• Create a custom property in HubSpot (e.g., total_invoiced)
• Set up a QuickBooks → HubSpot mapping for the invoice amount
• Direction: QuickBooks → HubSpot only

Sync deal amounts to QuickBooks:

• Map HubSpot Deal amount to a QuickBooks Customer custom field
• This helps accounting teams see expected revenue

These are optional and depend on your workflow. The primary mapping (Contacts/Companies → Customers) works independently.

Step 7: Test the Mapping

Before going live:

1. Click Test Sync

2. Review the preview showing what would sync

3. Check for:

   • DisplayName uniqueness (QuickBooks rejects duplicates)
   • Address fields populating correctly
   • Email matching working as expected

4. Adjust configuration and test again if needed

Step 8: Run Initial Sync

Once testing looks good:

1. Click Sync Now
2. Choose Full Sync for initial population
3. Monitor progress in real-time
4. Review completion statistics

Expected Results:

• HubSpot Contacts created as QuickBooks Customers
• Existing QuickBooks Customers matched by email and updated

Step 9: Enable Scheduled Sync

Set up automatic syncing:

1. Go to mapping Settings
2. Enable Scheduled Sync
3. Choose frequency: Every hour (accounting data doesn't typically need real-time updates)
4. Save

Verification

Check HubSpot

1. Open a contact that should have synced
2. Verify the contact data is current

Check QuickBooks

1. Go to Sales → Customers
2. Find the synced customer
3. Verify name, email, phone, and address are populated

Review Sync Logs

1. Go to Syncs
2. Click on recent sync jobs
3. Verify success rates and any errors

Common Issues & Solutions

DisplayName Conflict

Cause: QuickBooks requires unique DisplayName values. Two contacts with the same name cause a conflict.

Solution: Use a concatenate transform that includes email or company: {firstname} {lastname} ({company}).

Address Fields Blank in QuickBooks

Cause: HubSpot address fields are empty for the synced contacts.

Solution: Check that HubSpot contacts have address data populated. QuickBooks won't create partial addresses — if BillAddr.Line1 is empty, the entire address block may be skipped.

Email Not Matching

Cause: HubSpot stores john@example.com but QuickBooks has John@Example.com.

Solution: Enable case-insensitive matching and add the lowercase transform to the email field pair.

QuickBooks API Rate Limits

Cause: QuickBooks allows 500 requests per minute. Large syncs may hit this limit.

Solution: FluxCascade handles rate limiting automatically with retries. For very large initial syncs (10,000+ records), consider syncing during off-hours.

Best Practices

1. Use one-way sync for most setups – HubSpot owns contact data; QuickBooks is for accounting

2. Sync only when needed – Hourly or daily frequency is usually sufficient for accounting

3. Handle DisplayName carefully – Use a format that stays unique as your customer base grows

4. Don't sync financial data to HubSpot without validation – Invoice amounts in a CRM can cause confusion if not clearly labeled

5. Monitor for DisplayName collisions – Check sync logs for uniqueness errors regularly

Next Steps

• Field Transformations – Advanced data transformation options
• Error Handling – Handle sync failures
• Sync Scheduling – Configure sync frequency