Connect to QuickBooks

This guide walks you through connecting the QuickBooks Invoicing integration to your QuickBooks Online account using OAuth authentication.

Prerequisites

Before connecting, ensure you have:

• Successfully installed the integration from HubSpot Marketplace
• Super Admin permissions in HubSpot
• Completed Intuit Developer setup with your app created
• Your Client ID from Intuit Developer Portal
• Your Client Secret from Intuit Developer Portal
• QuickBooks Company Admin access for OAuth authorization
• Decided on environment: Sandbox or Production

Overview

Connecting to QuickBooks is a one-time setup that establishes OAuth authorization between HubSpot and your QuickBooks account. After connection, all HubSpot users (with appropriate permissions) can create invoices without reconnecting.

Estimated Time: 5-10 minutes

Step 1: Access Settings Page

Navigate to the integration settings:

Option A: Via Connected Apps

1. In HubSpot, click the Settings gear icon (top right)
2. Navigate to Integrations → Connected Apps
3. Find QuickBooks Invoicing in the list
4. Click on the app name or Configure button

Option B: Via CRM Card

1. Open any deal record in HubSpot
2. Click the QuickBooks Invoices tab
3. Click Settings link or gear icon (if visible)

The settings page should open with multiple tabs.

Step 2: Select Environment

Choose between Sandbox (testing) and Production (live):

1. In the Authentication tab, find the Environment selector
2. Choose your environment:
   • Sandbox: For testing with sample data
   • Production: For live business operations

Important: The environment you select must match your credentials. Sandbox requires Development credentials; Production requires Production credentials.

Decision Guide:

See Environment Selection for detailed comparison.

Step 3: Enter Client ID

Enter your Intuit Developer app credentials:

1. Open the Intuit Developer Portal  in a new tab

2. Navigate to My Apps → Select your app → Keys & credentials

3. Locate your Client ID:

   • For Sandbox: Use Development section Client ID
   • For Production: Use Production section Client ID

4. Copy the Client ID (click the copy icon)

5. Return to HubSpot settings

6. Paste the Client ID into the Client ID field

Client ID Format:

• Approximately 40-50 characters
• Alphanumeric (letters and numbers)
• No special characters or spaces

Tip: Keep the Intuit Developer Portal tab open - you’ll need it for the Client Secret next.

Step 4: Enter Client Secret

Enter your Client Secret (more sensitive than Client ID):

1. In the Intuit Developer Portal (Keys & credentials page)
2. Locate the Client Secret field (below Client ID)
3. Click Show or the eye icon to reveal the secret
4. Click the copy icon to copy the secret
5. Return to HubSpot settings
6. Paste the Client Secret into the Client Secret field

Client Secret Format:

• Approximately 50-70 characters
• Alphanumeric (letters and numbers)
• Case-sensitive
• Longer than Client ID

Security: The Client Secret is like a password. Never share it publicly or commit it to version control.

Encryption: Your Client Secret is encrypted before storage using AES-256-GCM with a derived key unique to your HubSpot account. See Security Best Practices.

Step 5: Save Credentials (if applicable)

Some implementations may require saving credentials before connecting:

1. Look for a Save button below the credential fields
2. If present, click Save
3. Wait for confirmation message: “Credentials saved”

If there’s no Save button, credentials are saved automatically when you connect.

Step 6: Connect to QuickBooks

Initiate the OAuth authorization flow:

1. Click the Connect to QuickBooks button
2. A new window or tab will open (Intuit’s authorization page)
3. You’ll be redirected to appcenter.intuit.com

Browser Note: If the window is blocked by a popup blocker, allow popups for this site and try again.

Step 7: Sign In to QuickBooks

On Intuit’s authorization page:

1. If not already signed in, enter your QuickBooks credentials:

   • Email address
   • Password

2. Click Sign In

Important: Use QuickBooks Company Admin credentials. Only admins can authorize third-party apps.

If you’re already signed in to QuickBooks, this step will be skipped automatically.

Step 8: Select QuickBooks Company

If you have access to multiple QuickBooks companies:

1. You’ll see a list of companies you can access
2. Select the company you want to connect to the HubSpot integration
3. Click Continue or Next

For Sandbox:

• You’ll see your sandbox test companies
• Select the sandbox company you created for testing

For Production:

• You’ll see your real QuickBooks Online companies
• Select the company where you want to create invoices

Tip: Double-check you’re selecting the correct company. You can change this later by disconnecting and reconnecting.

Step 9: Authorize Permissions

Review and approve the permissions requested:

1. Intuit shows the permissions the app is requesting:

   • Accounting scope: Create invoices, customers; read products, tax codes

2. Review the permissions carefully

3. Click Authorize or Connect

What you’re authorizing:

• The HubSpot integration can create invoices in your QuickBooks company
• The integration can create customers (synced from HubSpot contacts)
• The integration can read tax codes and products (to show in dropdowns)

What you’re NOT authorizing:

• The integration cannot delete invoices or customers
• Cannot access bank accounts or financial reports
• Cannot modify existing QuickBooks data (except invoices it created)

Privacy Note: OAuth tokens are encrypted and can be revoked anytime by disconnecting.

Step 10: Redirected Back to HubSpot

After authorizing:

1. Intuit redirects you back to HubSpot automatically
2. The redirect URL will be: https://hubspot.structur.app/quickbooks/oauth-callback
3. You may see a brief “Processing…” message
4. You’ll be returned to the HubSpot settings page

If redirect fails:

• Check that the redirect URI is configured in Intuit Developer Portal
• Verify it matches exactly: https://hubspot.structur.app/quickbooks/oauth-callback
• See Troubleshooting below

Step 11: Verify Connection

Confirm the connection was successful:

1. The Authentication tab should now show:

   • Status: “Connected” or green checkmark
   • QuickBooks Company: Name of the connected company
   • Connection Date: When you connected
   • Disconnect button (instead of Connect button)

2. Verify the displayed company name matches the one you selected

Success indicators:

• ✅ Status shows “Connected”
• ✅ QuickBooks company name displayed
• ✅ No error messages
• ✅ Disconnect button visible

Step 12: Test the Connection

Verify the integration can access QuickBooks:

Test 1: View CRM Card

1. Navigate to any deal record in HubSpot
2. Click the QuickBooks Invoices tab
3. Card should load without errors
4. Should show “Ready to create invoice” or similar (not “Not Connected”)

Test 2: Load Dropdowns (in Defaults Tab)

1. Go to settings Defaults tab
2. Click the Default Tax Code dropdown
3. You should see tax codes from your QuickBooks company
4. Click the Default Product dropdown
5. You should see products/services from your QuickBooks company

If dropdowns are empty:

• QuickBooks company may not have tax codes or products set up
• Add them in QuickBooks first, then refresh HubSpot settings

Test 3: Create a Test Invoice (Optional)

For a complete test:

1. Open a deal record with an associated contact
2. Click QuickBooks Invoices tab
3. Click Create Invoice
4. Fill in basic details
5. Submit the invoice
6. Verify the invoice appears in QuickBooks

See Creating Invoices for detailed instructions.

What Happens After Connection

OAuth Tokens Created

When you successfully connect:

1. Access Token generated by QuickBooks:

   • Valid for 1 hour
   • Used for API calls to QuickBooks
   • Encrypted and stored in integration database

2. Refresh Token generated by QuickBooks:

   • Valid for 100 days (rolling expiration)
   • Used to obtain new access tokens
   • Encrypted and stored in integration database

Auto-Refresh: The integration automatically refreshes the access token every hour. You don’t need to reconnect.

Token Security: Both tokens are encrypted using AES-256-GCM with derived keys (PBKDF2, 100,000 iterations). Unique encryption key per HubSpot account.

Integration Can Now…

✅ Create invoices in QuickBooks ✅ Create customers from HubSpot contacts ✅ Read tax codes and products for dropdowns ✅ Send invoice emails via QuickBooks ✅ Access the connected QuickBooks company

Integration Cannot…

❌ Delete invoices or customers ❌ Access bank accounts or financial data ❌ Modify existing QuickBooks transactions (other than its own invoices) ❌ Access other QuickBooks companies (only the connected one) ❌ Access your data after you disconnect (tokens deleted immediately)

Connection Lifespan

How Long Does Connection Last?

Indefinitely, as long as:

• You don’t manually disconnect
• You don’t uninstall the app
• The integration is used at least once every 100 days
• Tokens aren’t manually revoked in QuickBooks

Token Refresh:

• Access token: Refreshed automatically every hour
• Refresh token: Renewed with each use (rolling 100-day expiration)

Inactivity:

• If unused for 100+ days, refresh token expires
• You’ll need to reconnect (repeat OAuth flow)
• Settings and credentials preserved (just need to re-authorize)

Troubleshooting Connection Issues

”Invalid Client Credentials” Error

Cause: Incorrect Client ID or Secret

Solutions:

1. Verify you copied the full Client ID and Secret (no truncation)
2. Check for extra spaces before or after credentials
3. Ensure environment matches credentials:
   • Sandbox environment → Development credentials
   • Production environment → Production credentials
4. Regenerate credentials in Intuit portal if necessary
5. Copy credentials again and retry

”Redirect URI Mismatch” Error

Cause: Redirect URI not configured in Intuit Developer Portal

Solutions:

1. Go to Intuit Developer Portal → Your App → Keys & credentials
2. Scroll to Redirect URIs section
3. Verify this URI is listed:

   https://hubspot.structur.app/quickbooks/oauth-callback

4. If not present, add it exactly as shown (no trailing slash)
5. Click Save
6. Wait 1-2 minutes and retry connection

See Configure OAuth for detailed redirect URI setup.

”You Don’t Have Permission” During OAuth

Cause: Not a QuickBooks Company Admin

Solutions:

1. Sign out of QuickBooks
2. Sign in with a Company Admin account
3. Retry the OAuth flow
4. Or ask a QuickBooks admin to complete the authorization

Connection Succeeds But Dropdowns Empty

Cause: QuickBooks company has no tax codes or products

Solutions:

1. Log into QuickBooks Online
2. Add at least one tax code:
   • Go to Taxes → Sales Tax
   • Set up sales tax or create a non-taxable rate
3. Add at least one product/service:
   • Go to Sales → Products and Services
   • Click New → Create a product or service
4. Return to HubSpot settings and refresh

OAuth Window Closed Before Completion

Cause: User accidentally closed the OAuth window

Solutions:

1. Click Connect to QuickBooks again
2. Complete the entire OAuth flow without closing the window
3. If window keeps closing automatically, disable popup blockers

”Network Error” or “Timeout”

Cause: Network connectivity issues

Solutions:

1. Check internet connection
2. Disable VPN temporarily (if using one)
3. Try different browser
4. Check firewall isn’t blocking Intuit domains
5. Wait a few minutes and retry

Switching Companies or Environments

Connecting to a Different QuickBooks Company

If you want to change which QuickBooks company is connected:

1. Click Disconnect in the Authentication tab
2. Click Connect to QuickBooks again
3. During OAuth flow, select the different company
4. Complete authorization

Settings (default tax code, product) are preserved.

Switching from Sandbox to Production

To move from testing to live use:

1. Click Disconnect (disconnects from Sandbox)
2. Change Environment to “Production”
3. Enter Production Client ID and Secret
4. Click Connect to QuickBooks
5. Select your production QuickBooks company
6. Complete authorization

See Environment Selection for detailed migration guide.

Security and Privacy

Data Access

After connecting, the integration can:

• ✅ Read HubSpot deals and contacts (OAuth scopes approved during installation)
• ✅ Create invoices and customers in QuickBooks
• ✅ Read tax codes and products from QuickBooks

The integration cannot:

• ❌ Modify HubSpot data (read-only OAuth scopes)
• ❌ Access QuickBooks financial reports or bank accounts
• ❌ Access your data after disconnection (tokens deleted)

Privacy Guarantee

After you disconnect:

1. OAuth tokens permanently deleted (< 1 second)
2. Encryption keys rotated (old encrypted tokens unreadable)
3. Integration loses all access to QuickBooks
4. No API calls possible without tokens

We cannot access your QuickBooks data after disconnection. Tokens are the only access method.

See Data Sharing Reference for comprehensive privacy details.

Next Steps

Now that you’re connected:

1. Configure Default Settings - Set up default tax codes and products (3 minutes)
2. Create Your First Invoice - Start using the integration (5 minutes)
3. Best Practices - Learn optimal workflows

If you encounter issues:

• Authentication Troubleshooting - Comprehensive troubleshooting guide
• Support - Contact us for help

Additional Resources

• Environment Selection - Sandbox vs Production detailed guide
• Get Credentials - How to find Client ID and Secret
• OAuth Scopes Reference - What permissions are granted
• Intuit OAuth Documentation  - Official Intuit OAuth guide