QuickBooks Online Integration

Set up and manage QuickBooks Online sync for customers, estimates, and invoices, and see how payments move

QuickBooks Online Integration

Connect DrillerDB to QuickBooks Online and the invoices and estimates you create in DrillerDB post into QuickBooks for you, so you are not typing the same job twice.

The sync runs mainly one way. DrillerDB sends records to QuickBooks. Some records also come back on their own: new estimates and invoices, products and services, and the paid amount and status of your invoices. The two systems are not a live two-way mirror.

Before you start

You need the admin role in DrillerDB. The Integrations page is admin only.
You need a QuickBooks Online account and the right to authorize an app on it.
Know which QuickBooks company you want to connect. You choose it during sign-in.

Using QuickBooks Desktop instead? That is a different setup with its own guide. It uses the free QuickBooks Web Connector on a Windows PC.

Connect QuickBooks Online

Go to Settings > Integrations and open the Accounting section.
Find the QuickBooks Online card and click Connect to QuickBooks.
Sign in to QuickBooks and pick the company you want to connect.
Approve the access QuickBooks asks about.
Wait to land back on the Integrations page. A green QuickBooks Online connected banner appears at the top and stays until you dismiss it, and the card shows Connected.

DrillerDB asks QuickBooks for accounting access, which covers the customers, vendors, items, invoices, estimates, and payments it needs to do the sync.

The connection link is good for 15 minutes and works one time. Finish the sign-in in one sitting rather than leaving the QuickBooks tab open and coming back to it.

What happens during the connection

After you approve at QuickBooks, your browser passes through a DrillerDB page for a moment while the approval is handed back, then returns you to Settings > Integrations on its own. You do not need to do anything on that page. You know it worked when the green QuickBooks Online connected banner appears and the card shows Connected. If the connection fails instead, a red QuickBooks Online connection failed banner appears with a sentence saying what went wrong. Either way the banner stays on screen until you dismiss it with the x.

The banner is the quicker answer of the two. Connecting makes the page re-check every integration, so the cards can take a moment to catch up, and the count at the top of the page says when it is still checking. A card that has not finished checking is not a failed connection.

If you have more than one QuickBooks company

A standard account connects one QuickBooks company at a time. To move to a different one, disconnect and connect again.
On an Enterprise account with several billing entities, each entity connects its own QuickBooks company from Settings > Billing Entities.

Choose what syncs automatically

Connecting and syncing are two different settings. After you connect, open Accounting > Settings and find Sync Behavior.

Automatically sync to QuickBooks is the master switch. On, new invoices and estimates post to QuickBooks by themselves. Off, nothing posts on its own and you push records yourself with Queue Full Sync.
Some companies also get separate Invoices and Estimates / Proposals switches, so you can hold one type back while the other keeps posting. If you do not see them, only the master switch applies to your company.

There is no setting for how often the sync runs and no setting to pick a direction. Records go over on their own once the master switch is on.

What gets synced

DrillerDB sends these to QuickBooks:

Customers - the customer on the invoice, created in QuickBooks if it is not there yet. A person is created with their first and last name and no company name. A business is created with its business name. Customers already in QuickBooks are not changed.
Items - the service and product lines your invoices and estimates use, created if needed
Invoices - number, date, line items, amounts, and terms
Estimates and proposals - when the estimates switch is on

DrillerDB creates a customer and its items before the invoice that uses them, so you do not get broken references in QuickBooks. There is nothing to set up for that.

Payments you record in DrillerDB are not sent to QuickBooks Online unless payment sync is turned on for your connection. Until it is, record those payments in QuickBooks too. A payment recorded in QuickBooks comes back to DrillerDB on its own; see Payments recorded in QuickBooks.

DrillerDB sends an estimate to QuickBooks only if DrillerDB created it there. An estimate that came in from QuickBooks is not sent back, so changes you make to it in DrillerDB do not reach QuickBooks.

What comes back from QuickBooks

While QuickBooks Online is connected, DrillerDB checks it every few hours and brings in what is new or changed since the last check. You do not have to press anything. The first check on a new connection reads every estimate, invoice, and product and service in your QuickBooks file, not only recent ones.

Each check brings in:

Estimates - a new estimate becomes a project, the same way the import makes one
Invoices - a new invoice comes in as an invoice
Products and services - added to your catalog, or updated if you already have them
Customers - created when an estimate or invoice needs one

For an invoice that started in DrillerDB, only the paid amount, balance, and payment status come back. If you change its lines, total, or terms in QuickBooks, the DrillerDB invoice keeps what was entered in DrillerDB. For an invoice that started in QuickBooks, a later check also brings over changes to its lines, total, due date, and terms.

A job that came in from a QuickBooks invoice is already billed in QuickBooks. If you create a new invoice on that job in the console, DrillerDB warns you before it bills the job again. See A job that came from a QuickBooks invoice.

The checks do not bring in vendors or payment records. Your whole customer list, including customers with no estimates or invoices, comes in only if customer syncing is turned on for your company, and it is off by default. The import brings in the customer list whenever you run it.

Automatically sync to QuickBooks controls only what DrillerDB sends. Turning it off does not stop these checks, and no setting turns them off while QuickBooks stays connected.

On an Enterprise account with several billing entities, these checks do not run.

Import from QuickBooks

The automatic checks in What comes back from QuickBooks start as soon as you connect. The import is the step you run yourself, and it also brings in your whole customer list. You do not have to wait for the first check before you run it. To start it, go to Accounting > Settings and click the Integrations (QuickBooks) heading to open that section. It starts closed, and nothing inside it is on the page until you open it, so the button is not where you can see it when the page first loads. Inside, the connected QuickBooks panel has Import from QuickBooks Online beside Queue Full Sync. The button is there only once QuickBooks is connected, and you need the admin or office role to run it.

The import brings across:

Customers - matched to the customer you already have where one lines up, created if not. A person comes in with their first and last name. Their Business field stays empty when QuickBooks has only the person's own name, whether it is written "First Last" or "Last, First". A customer with a company name comes in with that as the business. A contact you already have keeps its current Business until you change it.
Products and services - the catalog your invoice and estimate line pickers read
Estimates - each one becomes its own project, carrying the job-site address from the estimate
Invoices - with their line items, and the paid amount and payment status

The import does not bring in vendors or payment records. A payment recorded in QuickBooks updates the paid amount and status on the invoice it belongs to. See Payments recorded in QuickBooks below.

It takes everything, with no date cutoff.

Once it has finished you can run it again with the same button. Anything it already imported is skipped, so a later run does not duplicate an earlier one.

There is no undo. Nothing takes an import back out, so anything you decide you did not want has to be removed by hand.

While it is running

The import runs in the background on DrillerDB's servers, not in your browser. It usually starts within about five minutes of your click. You can close the page while it works.

A panel under the buttons shows where the import is, and it updates on its own:

Import queued - waiting for the importer to pick it up
Import running - a bar for each kind of record, with a count such as "Invoices: 120 of 400"
Import interrupted, retrying - an attempt failed, and the import tries again from where it stopped
Import failed - the import gave up after several attempts, and the panel says why
Import finished - your QuickBooks records are in DrillerDB

While the import runs, the panel has rows for Vendors and Payments too. The import does not bring those in, so both rows show a dash.

While an import is queued or running, the button reads Import queued... or Import running... and you cannot click it. That is true in every tab, and after a reload. If a second click does get through, it joins the import that is already going instead of starting another one.

When the panel reads Import finished, look in Accounting for the customers, projects, and invoices it brought across. The panel does not say how many records came in.

Clicking again used to duplicate the import

Each click used to start its own import, and two running at once could not see each other's work, so the same customers and projects came in twice or three times. DrillerDB now runs one import per company at a time. If you already have duplicates from clicking a slow page more than once, they are from that older behaviour and still have to be removed by hand.

What your estimate statuses become

The status on a QuickBooks estimate decides the status of the project it creates:

In QuickBooks	In DrillerDB
Accepted or Converted	Approved
Closed	Completed
Rejected	Cancelled
Anything else, or no status at all	Proposal

If you already typed some of these in by hand

Before it creates a project, the import looks for one you already have. It matches when the job number is the same as the QuickBooks estimate number, or when that customer has exactly one job dated the same day as the estimate. If neither matches, you end up with a second copy of that job. The same goes for products and services you have already entered.

The import does not tell you which jobs or products it matched and which it copied. After it finishes, check your jobs and your products and services list for second copies.

So if you are still setting up, run the import first and then fill in only what QuickBooks does not already have.

Payments recorded in QuickBooks

When a customer pays an invoice inside QuickBooks, the paid amount and payment status of the matching DrillerDB invoice update on their own. You do not have to run the import. QuickBooks tells DrillerDB when a payment is recorded, and the checks every few hours catch anything that notice missed.

When QuickBooks sends that notice, the payment also comes across as a payment of its own, against the invoice it settles. If you keep your books in DrillerDB Accounting, a sweep runs every hour to pick up any payment the notice missed. The sweep is there because the notice is not reliable on its own.

The same payment is never brought across twice, so the hourly sweep does not duplicate what has already arrived.

If a payment is deleted in QuickBooks

When someone deletes a payment in QuickBooks, DrillerDB removes the payment it brought in from QuickBooks and works out the invoice's paid amount and balance again. By default, admin and office users get a QuickBooks payment deleted notification that names the amount removed and the invoice.

DrillerDB keeps the payment when it cannot be sure the payment came only from QuickBooks. For example, it keeps a payment someone recorded in DrillerDB, a payment on a void invoice, or a payment that has a refund recorded against it. The notification then says DrillerDB still records the amount and asks you to review the payment.

When a payment is changed, moved to another invoice, or voided in QuickBooks, the notification shows what DrillerDB still records for it and asks you to review it.

Job-site sales tax

Under Sync Behavior, Tax by job-site location sends the well or job-site address to QuickBooks as the shipping address. QuickBooks then works out sales tax by where the work happened instead of by the customer's billing address.

Turn this on only if you have Automated Sales Tax switched on in QuickBooks Online. QuickBooks does the tax math, not DrillerDB.

Check sync activity

The Sync Activity Log on the Accounting > Settings page lists what went to QuickBooks and when. Three buttons sit above it:

Refresh Status re-reads the connection and updates the badge.
Refresh Token renews the QuickBooks sign-in without a full reconnect.
Open QuickBooks opens QuickBooks Online in a new tab.

Clear old (90d+) on the log removes received successes older than 90 days. Successful pushes and accounting receipts are kept.

A held QuickBooks document

When the QuickBooks import cannot tie a document to one DrillerDB contact with certainty, it holds the document instead of guessing. Its row in the Sync Activity Log shows Choose customer. Pick the DrillerDB contact that is that QuickBooks customer and click Connect contact. The held documents import on the next QuickBooks import. Only a contact that is not already connected to another QuickBooks customer can be chosen. If the same customer is in QuickBooks twice, you can also merge the two there. Dismiss closes the review, and the entry stays in the log.

To check the connection itself rather than the sync, use Test Connection on the QuickBooks Online card under Settings > Integrations. It asks QuickBooks for a live answer and reports Connection successful, or tells you the connection failed and to try disconnecting and reconnecting.

Disconnect or switch QuickBooks companies

Go to Settings > Integrations > QuickBooks Online.
Click Disconnect from QuickBooks and confirm.

Records already synced stay in both systems. You can reconnect later, and reconnecting to the same QuickBooks company keeps your customers and invoices matched rather than creating duplicates.

Troubleshooting

"That connection link expired before it was finished. Click Connect again to start over."

The connection link timed out. It lasts 15 minutes, which is easy to hit on a slow setup call. Click Connect to QuickBooks again and finish the QuickBooks sign-in without stopping. Nothing was connected, so there is nothing to undo.

"That connection link was already used. Click Connect again to start a new one."

Each link works one time. This usually means the browser Back button, or an old link reopened. If the card already reads Connected, you are done. If not, click Connect to QuickBooks again.

"That connection link was not valid. Click Connect again to start a new one."

DrillerDB did not recognize the link that came back. That usually means it was edited, was copied out of an email or a chat, or came from a different browser than the one that started the connection. Nothing was connected. Go to Settings > Integrations and click Connect to QuickBooks to start a fresh one, and finish it in the same browser.

"The connection was cancelled before it finished. Nothing was changed."

You closed the QuickBooks window or declined at the approval screen. Nothing was linked. Click Connect to QuickBooks when you are ready to try again.

"We could not finish the connection. Please try again, and contact support if it keeps happening."

QuickBooks approved the connection but DrillerDB could not complete it. Try once more. If it happens again, contact support rather than retrying repeatedly.

It says "not connected" right after you reconnected?

The connection status is read when the page opens, so it can show a stale "not connected" from before you reconnected. Reload the Settings > Integrations page. If it still looks wrong, check you are looking at the QuickBooks Online connection and not a different accounting integration.

Sync stopped, or you got a "Please reconnect your accounting integration" message?

This almost always means the QuickBooks access token expired. Tokens expire on a schedule, and when one lapses, syncing quietly stops until you reconnect.

Go to Settings > Integrations > QuickBooks Online.
Sign in to QuickBooks again and approve access.
Check the Sync Activity Log to confirm records start syncing again.

Reconnecting re-links the same QuickBooks company, so your customers and invoices stay matched.

The card says Connected, but nothing reaches QuickBooks?

Being connected and posting automatically are two different settings. Open Accounting > Settings and check that Automatically sync to QuickBooks is on. If it is off, your records are waiting for you to push them with Queue Full Sync. Then read the Sync Activity Log to see what actually went over.

A single invoice will not sync?

Open the Sync Activity Log and read the error on that record. A common cause is a line item that needs to be matched to a QuickBooks item by hand before it can go over.

Integrations Overview - All integrations
Billing Settings - Invoice configuration
Invoicing - Creating invoices
Activity Log - Sync logs