Skip to Content
DocumentationStructur for QuickbooksConfigurationOverview

Configuration Overview

After installing the QuickBooks Invoicing integration, you need to configure it to connect to your QuickBooks account and set up default preferences. This section guides you through the configuration process.

Configuration Steps

The configuration process takes approximately 10-15 minutes and includes:

  1. Connect to QuickBooks - Enter OAuth credentials and authenticate (5-10 minutes)
  2. Add CRM Card to Deals - Enable the QuickBooks Invoices card on deal records (2 minutes)
  3. Configure Default Settings - Set up default tax codes and products (3-5 minutes)
  4. Select Environment - Choose Sandbox or Production (included in step 1)

Prerequisites

Before configuring, make sure you have:

  • Successfully installed the QuickBooks Invoicing integration from HubSpot Marketplace
  • Super Admin permissions in HubSpot
  • Completed Intuit Developer setup and have your credentials ready:
    • Client ID
    • Client Secret
    • Environment (Sandbox or Production)
  • QuickBooks Company Admin access (for OAuth authorization)

What You’ll Configure

QuickBooks Connection

Purpose: Establish OAuth connection between HubSpot and QuickBooks

What you’ll need:

  • Client ID from Intuit Developer Portal
  • Client Secret from Intuit Developer Portal
  • QuickBooks account login credentials

What you’ll do:

  1. Enter credentials in HubSpot settings
  2. Choose environment (Sandbox or Production)
  3. Complete OAuth authorization flow
  4. Select QuickBooks company to connect

Result: Integration can access your QuickBooks account to create invoices and customers

Add CRM Card to Deals

Purpose: Enable the QuickBooks Invoices card to appear on deal records

What you’ll do:

  1. Navigate to HubSpot Settings → Objects → Deals
  2. Go to the Properties tab
  3. Scroll to the Cards section
  4. Find and enable the “QuickBooks Invoices” card
  5. Ensure it’s visible in your deal record layout

Result: QuickBooks Invoices tab appears in the middle column of all deal records

Note: The card may appear automatically after installation. If you don’t see it, follow these steps to enable it manually.

Step-by-Step Instructions:

  1. In HubSpot, click the Settings gear icon (top right)
  2. Navigate to Objects → Deals
  3. Click the Record Customization tab
  4. Click on the view you want to edit (or create a new view)
  5. In the Overview column, click “Add card”
  6. Find “QuickBooks Invoices” in the list of available cards
  7. Click to add the card to the view
  8. Save your changes
  9. The card will now appear in the middle column when viewing deal records

Verification: Open any deal record and check the middle column for the “QuickBooks Invoices” card.

Default Tax Code

Purpose: Pre-select a tax code for invoice creation

What you’ll choose:

  • A tax code from your QuickBooks company
  • Examples: “Sales Tax”, “Non-Taxable”, “Tax Exempt”

Benefits:

  • Speeds up invoice creation (tax code pre-selected)
  • Ensures consistency across invoices
  • Reduces user errors

Optional: You can skip this and select tax code manually for each invoice

Default Product

Purpose: Pre-select a product/service for invoice line items

What you’ll choose:

  • A product or service from your QuickBooks company
  • Examples: “Services”, “Consulting”, “Sales”

Benefits:

  • Faster invoice creation
  • Consistent product categorization
  • Simplified user experience

Optional: You can skip this and select product manually for each invoice

Configuration Workflow

Install App → Access Settings → Enter Credentials → Connect to QuickBooks → Configure Defaults → Start Creating Invoices

Step-by-Step Process

  1. Access Settings Page:

    • Go to HubSpot Settings → Integrations → Connected Apps
    • Click on QuickBooks Invoicing
    • Settings page opens with multiple tabs

  2. Authentication Tab:

    • Select environment (Sandbox or Production)
    • Enter Client ID
    • Enter Client Secret
    • Click “Connect to QuickBooks”
    • Complete OAuth authorization

  3. Defaults Tab:

    • Select default tax code (optional)
    • Select default product (optional)
    • Save settings

  4. Add CRM Card:

    • Navigate to Settings → Objects → Deals
    • Click the “Record Customization” tab
    • Click on the view to edit
    • In the overview column, click “Add card”
    • Find “QuickBooks Invoices” card and add it
    • The card will appear in the middle column of deal records

  5. Verification:

    • Check connection status shows “Connected”
    • QuickBooks company name displayed
    • Default settings saved
    • CRM card visible on deal records

  6. Start Using:

    • Open a deal record
    • Click QuickBooks Invoices tab (middle column)
    • Create your first invoice

Configuration Tabs

The settings page includes the following tabs:

Authentication Tab

What’s here:

  • Environment selector (Sandbox/Production)
  • Client ID input field
  • Client Secret input field
  • Connect to QuickBooks button
  • Connection status display
  • QuickBooks company name (when connected)
  • Disconnect button (when connected)

Who can access: Super Admins only

When to use: Initial setup, switching environments, reconnecting

Defaults Tab

What’s here:

  • Default tax code dropdown
  • Default product dropdown
  • Save button

Who can access: Super Admins only

When to use: Initial setup, changing defaults

Environment Selection

You must choose between two QuickBooks environments:

Sandbox (Development)

Use for:

  • Testing the integration with sample data
  • Training users on invoice creation
  • Troubleshooting issues safely
  • Development and QA

Credentials needed: Development Client ID and Secret

QuickBooks company: Sandbox test company

Data: Test data only (not real business data)

Production (Live)

Use for:

  • Creating real invoices for customers
  • Live business operations
  • After testing in Sandbox is complete

Credentials needed: Production Client ID and Secret

QuickBooks company: Real QuickBooks Online company

Data: Live business data

Configuration Best Practices

Before You Start

✅ Do:

  • Complete Intuit Developer setup first
  • Have credentials ready (copy/paste from Intuit portal)
  • Decide on Sandbox vs Production before connecting
  • Test in Sandbox before using Production
  • Document your configuration choices

❌ Don’t:

  • Rush through configuration without reading instructions
  • Use Production credentials for testing
  • Share credentials via email or unsecure channels
  • Skip Sandbox testing for production deployments

During Configuration

✅ Do:

  • Double-check credentials before saving (copy/paste to avoid typos)
  • Verify environment matches your credentials
  • Test the connection immediately after setup
  • Configure default tax code and product (saves time later)
  • Note which QuickBooks company you connected to

❌ Don’t:

  • Enter Production credentials when testing
  • Connect to the wrong QuickBooks company
  • Skip testing after configuration
  • Ignore error messages

After Configuration

✅ Do:

  • Create a test invoice to verify everything works
  • Document which environment you’re using
  • Train users on invoice creation
  • Set up a process for invoice review
  • Plan for production migration (if starting in Sandbox)

❌ Don’t:

  • Assume everything works without testing
  • Give all users access before testing
  • Skip user training
  • Forget to switch to Production when ready

Common Configuration Scenarios

Scenario 1: First-Time Setup for Testing

Goal: Test the integration before using with real data

Configuration:

  1. Environment: Sandbox
  2. Credentials: Development Client ID and Secret
  3. QuickBooks company: Sandbox test company
  4. Default tax code: Any tax code from sandbox
  5. Default product: Any product from sandbox

Next steps: Create test invoices, train users, verify functionality

Scenario 2: First-Time Setup for Production

Goal: Go live with real invoice creation

Prerequisites: Tested thoroughly in Sandbox

Configuration:

  1. Environment: Production
  2. Credentials: Production Client ID and Secret
  3. QuickBooks company: Real QuickBooks Online company
  4. Default tax code: Your most commonly used tax code
  5. Default product: Your default service/product

Next steps: Create first real invoice, monitor for issues

Scenario 3: Switching from Sandbox to Production

Goal: Migrate from testing to live use

Steps:

  1. Disconnect from Sandbox (in settings)
  2. Change environment to Production
  3. Enter Production credentials
  4. Connect to production QuickBooks company
  5. Reconfigure default tax code and product (may differ from sandbox)

See Environment Selection for detailed steps.

Scenario 4: Reconnecting After Credential Rotation

Goal: Update credentials for security

Steps:

  1. Disconnect in HubSpot settings
  2. Rotate credentials in Intuit Developer Portal
  3. Enter new Client Secret in HubSpot
  4. Reconnect to QuickBooks
  5. Verify connection works

Troubleshooting Configuration

Can’t Access Settings Page

Possible causes:

  • Not a Super Admin in HubSpot
  • App not fully installed
  • Browser issue

Solutions:

  1. Verify you’re a Super Admin
  2. Try different browser
  3. Clear cache and retry
  4. Contact HubSpot support

See Authentication Troubleshooting for more details.

OAuth Connection Fails

Possible causes:

  • Incorrect Client ID or Secret
  • Wrong environment selected
  • Redirect URI mismatch
  • QuickBooks account access issues

Solutions:

  1. Verify credentials are correct (copy from Intuit portal)
  2. Check environment matches credentials (Sandbox vs Production)
  3. Verify redirect URI in Intuit Developer Portal
  4. Sign in to QuickBooks with admin account
  5. Try different browser

See Authentication Troubleshooting for comprehensive solutions.

Default Settings Won’t Save

Possible causes:

  • Not connected to QuickBooks yet
  • Invalid tax code or product ID
  • Network timeout

Solutions:

  1. Connect to QuickBooks first (required before setting defaults)
  2. Verify tax code exists in QuickBooks
  3. Verify product exists in QuickBooks
  4. Check network connection
  5. Retry saving

Security During Configuration

Credential Handling

Your credentials are secured during and after configuration:

Entry:

  • Client Secret entered in browser form (HTTPS)
  • Transmitted to backend via encrypted connection
  • Never stored in browser or logs

Storage:

  • Encrypted using AES-256-GCM before database storage
  • Unique encryption key derived per HubSpot account (PBKDF2, 100k iterations)
  • Cannot be decrypted without account-specific key

Usage:

  • Decrypted only in secure server-side context
  • Never transmitted back to browser
  • Used only for OAuth token exchange

See Security Best Practices for technical details.

OAuth Token Security

OAuth tokens obtained during configuration:

Tokens:

  • Access token (1-hour lifespan)
  • Refresh token (100-day lifespan, rolling)

Security:

  • Encrypted immediately upon receipt
  • Same encryption as credentials (AES-256-GCM, derived keys)
  • Auto-refreshed when access token expires
  • Deleted immediately upon disconnection

Privacy guarantee: After disconnection, tokens are permanently deleted and we cannot access your QuickBooks data.

Next Steps

Ready to configure the integration?

  1. Connect to QuickBooks - Start here for step-by-step connection guide
  2. Environment Selection - Understand Sandbox vs Production in detail
  3. Default Settings - Configure tax codes and products after connecting

Already configured? Start using the integration:

Additional Resources

Last updated on
Verify InstallationConnect to QuickBooks