Skip to main content

QuickBooks Integration

ContractorScope AI integrates with QuickBooks Online to keep your estimating and accounting in sync. Once connected, you can sync customers, convert accepted estimates into invoices, and keep your books up to date without double-entering data.

What the Integration Does​

The QuickBooks integration connects your ContractorScope AI account with your QuickBooks Online account. Here is what it enables:

  • Customer Sync — Your QuickBooks customers appear in ContractorScope AI, and new clients you add in ContractorScope AI can sync back to QuickBooks.
  • Invoice Creation — When a client accepts an estimate, you can create a QuickBooks invoice directly from ContractorScope AI with one click.
  • Payment Tracking — See payment status from QuickBooks reflected in ContractorScope AI.
  • Two-Way Sync — Changes in either system can be reflected in the other (configurable).

Requirements​

Before you connect, make sure you have:

  • A QuickBooks Online account (Simple Start, Essentials, Plus, or Advanced). QuickBooks Desktop is not supported.
  • Admin access to your QuickBooks Online account (you need permission to authorize third-party apps).
  • An active ContractorScope AI subscription (the integration is available on all paid plans).
info

The QuickBooks integration uses OAuth 2.0, the industry standard for secure authorization. ContractorScope AI never sees or stores your QuickBooks password. You authorize access through QuickBooks directly, and you can revoke it at any time.

Connecting QuickBooks​

Sign-in and company membership required

The QuickBooks connect, status, settings, and sync actions all require you to be signed in to ContractorScope AI as a member of the company you are connecting. These flows are protected — they will not run for an unauthenticated session or for a user who does not belong to the active company. If you are signed out, or switching between companies, sign in to the correct company first, then start the connection.

Step 1: Open the QuickBooks Connection​

  1. Click Settings in the left sidebar of ContractorScope AI.
  2. Select QuickBooks sync, then step through the short intro wizard to the last step. (Company admins can instead go to Company & users, which shows the same connection as a card with sync mode, sync safety, and user-access controls alongside it.)
  3. Click Connect to QuickBooks (or Connect, on the Company & users card).

Step 2: Authorize the Connection​

  1. A popup window opens showing the QuickBooks authorization page. Your ContractorScope AI tab stays open in the background.
  2. Sign in to your QuickBooks account if you are not already signed in.
  3. Select the QuickBooks company you want to connect (if you have more than one).
  4. Review the permissions ContractorScope AI is requesting:
    • Read and write customers
    • Read and write invoices
    • Read products and services
    • Read payments
  5. Click Connect to authorize.

The popup closes itself and returns you to the page you started from, where you will see a "QuickBooks connected" panel or a green "Connected" status.

Step 3: Initial Sync​

After connecting, ContractorScope AI runs an initial sync:

  1. Your QuickBooks customer list is imported into ContractorScope AI.
  2. This process usually takes 1 to 3 minutes depending on the size of your customer list.

You will see a progress indicator and a notification when the sync is complete.

QuickBooks connection authorization screen

tip

If you already have clients in ContractorScope AI, the system will attempt to match them with QuickBooks customers by name and email. Matched records are linked automatically. Unmatched records remain separate — you can link them manually later.

Syncing Customers​

From QuickBooks to ContractorScope AI​

Your QuickBooks customer list is available in ContractorScope AI after the initial sync. When you add a new customer in QuickBooks, they appear in ContractorScope AI within a few minutes (sync runs automatically on a regular interval).

The following fields are synced:

  • Customer name (display name)
  • Email address
  • Phone number
  • Billing address
  • Shipping address (used as job site address)

From ContractorScope AI to QuickBooks​

When you create a new client in ContractorScope AI:

  1. The system checks if a matching customer exists in QuickBooks.
  2. If no match is found, you are given the option to Create in QuickBooks when saving the client.
  3. Click the toggle to create the customer in both systems simultaneously.

Managing Linked Customers​

To see which customers are linked between the two systems:

  1. Go to Clients in the left sidebar.
  2. Linked clients show a small QuickBooks icon next to their name.
  3. Click on a client to see their linked QuickBooks customer ID.

To manually link a ContractorScope AI client with a QuickBooks customer:

  1. Open the client's profile.
  2. Click Link to QuickBooks.
  3. Search for and select the matching QuickBooks customer.
  4. Click Link.

To unlink a customer, click Unlink QuickBooks in the client profile.

Creating Invoices from Estimates​

This is the most powerful feature of the integration — turning accepted estimates into QuickBooks invoices without re-entering anything.

One-Click Invoice Creation​

  1. Open an estimate that has been Accepted by the client.
  2. Click the Create Invoice button (it appears once an estimate is accepted and QuickBooks is connected).
  3. Review the invoice preview:
    • Each line item's description, quantity, and price carry over from the estimate as its own invoice line — there is no separate QuickBooks product/service category mapping step.
    • Client information is pre-filled.
    • Payment terms carry over from the estimate.
    • Tax rates are applied based on your QuickBooks tax settings.
  4. Click Create in QuickBooks.
  5. The invoice is created in QuickBooks and a link appears in ContractorScope AI.
info

The invoice is created in QuickBooks as an unpaid invoice. You still manage payments, send reminders, and handle collections through QuickBooks as you normally would.

Progress Invoicing​

For larger projects with progress payments, you can create multiple invoices from a single estimate:

  1. Open the accepted estimate.
  2. Click Create Invoice.
  3. Select Progress Invoice instead of full invoice.
  4. Choose which line items or what percentage to include in this invoice.
  5. The system tracks how much has been invoiced and how much remains.

For example, if your payment terms are 50/25/25:

  • First invoice: 50% of the estimate total at project start.
  • Second invoice: 25% at rough-in completion.
  • Third invoice: 25% at final completion.

Two-Way Sync Options​

You control what syncs and in which direction. Go to Settings > Company & users and find the QuickBooks card to configure:

Sync Direction​

SettingWhat It Does
QuickBooks to ContractorScope AINew and updated QuickBooks customers appear in ContractorScope AI. One-way sync.
ContractorScope AI to QuickBooksNew clients and invoices created in ContractorScope AI sync to QuickBooks. One-way sync.
Two-WayChanges in either system sync to the other. This is the recommended setting.

Sync Frequency​

  • Real-Time — Changes sync within seconds. Best for businesses that need up-to-the-minute accuracy.
  • Every 15 Minutes — A good balance of freshness and performance. This is the default.
  • Hourly — Syncs once per hour. Suitable if you do not need immediate updates.
  • Manual Only — Sync only happens when you click the Sync Now button.

Conflict Resolution​

ContractorScope AI uses per-field conflict detection to protect your data when both sides are edited between syncs. Rather than one side silently overwriting the other, the system performs a three-way comparison — app value vs QuickBooks value vs the last-synced "base" value — for every tracked field:

  • One side changed, the other did not → the change is applied automatically. Nothing for you to do.
  • Both sides changed the same field → a conflict is recorded. Nothing is overwritten. A "N pending conflicts" badge appears on the QuickBooks settings card. Click it to open the Conflict Resolution modal, where you can review the app value vs the QuickBooks value side by side and pick the one to keep.

Conflict detection is active in Two-Way sync mode. One-way modes (QuickBooks Wins / ContractorScope AI Wins) skip conflict detection and always apply the authoritative side.

Tracked fields and entities:

EntityTracked Fields
ContactsDisplay name, email, phone
ProjectsProject / job name
EstimatesStatus (sent / accepted / rejected)
info

Estimate line items and totals are app-generated and do not sync back from QuickBooks. Only the estimate status field can produce a conflict.

warning

If a resolution cannot be confirmed (for example, because your QuickBooks authorization has expired or QuickBooks returned an error), the conflict stays pending rather than being silently dropped. This prevents a failed write from causing a silent revert. Reconnect or retry from the modal.

For a full walkthrough of the modal, the three-way diff logic, and troubleshooting stuck conflicts, see Conflict Resolution.

Disconnecting QuickBooks​

If you need to disconnect:

  1. Go to Settings > Company & users and find the QuickBooks card.
  2. Click Disconnect.
  3. Confirm the disconnection.

Disconnecting does not delete any data. Your ContractorScope AI clients, estimates, and any previously created QuickBooks invoices remain intact. You simply lose the live sync between the two systems.

You can reconnect at any time by following the connection steps again.

Troubleshooting​

"Authorization Expired" Error​

QuickBooks OAuth tokens expire periodically. If you see this error:

  1. Go to Settings > Company & users and find the QuickBooks card.
  2. Click Reconnect.
  3. Re-authorize through QuickBooks.
  4. Sync resumes automatically.

Customers Not Syncing​

If new QuickBooks customers are not appearing in ContractorScope AI:

  1. Check your sync frequency setting — if set to hourly, it may not have run yet.
  2. Click Sync Now to force an immediate sync.
  3. Verify the customer is active (not archived) in QuickBooks.
  4. Check that the customer has at least a name and email.

Invoice Creation Fails​

If clicking "Create in QuickBooks" results in an error:

  1. Verify the client is linked to a QuickBooks customer.
  2. Check that your QuickBooks subscription is active.
  3. Try clicking Sync Now then attempt again.

If the issue persists, contact support at info@contractorscopeai.com with the estimate number and the error message you see.

Next Steps​