Connect QuickBooks Online

Overview

Connect QuickBooks Online (QBO) to push customers, estimates, invoices, payments, purchase orders, and optional job costing data from Dirt Face into your books. Dirt Face supports QBO only (not QuickBooks Desktop).

Dirt Face is the source of truth for operations and job costing. QBO is the source of truth for accounting, expenses, and taxes. Sync sends accounting documents to QBO; it does not replace job profitability reporting inside Dirt Face.

Where in the app: Sidebar → Business Settings → Integrations → QuickBooks
Open: QuickBooks integration

Requires a Crew plan or higher plan and admin access to connect.

---

Before you connect

• An active QuickBooks Online subscription from Intuit
• Admin access to your Dirt Face account
• Crew plan or higher

If you use Multi-Location, read the section below before connecting each branch.

---

Connect your QuickBooks company

1. Open QuickBooks integration
2. Click Connect to QuickBooks
3. Sign in to Intuit and authorize Dirt Face
4. Select the QBO company file for the active location

After connecting, import tax codes (recommended first step), then review sync toggles and save.

To reconnect after token expiry, use Reconnect on the same page.

Warning: Disconnecting stops new syncs. Records already in both systems remain, but changes will not flow until you reconnect.

---

Multi-location and multiple QBO accounts

Yes. With Multi-Location enabled, each company profile (location) can connect to its own QBO company file.

• Switch locations using the header profile switcher
• Open QuickBooks integration again for each location and connect separately
• Each location needs its own QBO subscription from Intuit
• Sync settings, tax import, employee mappings, and sync history are per location

Without multi-location, one QBO company connects to the whole tenant.

The page shows a banner when multi-location is active reminding you which profile you are configuring.

---

Import sales tax codes

Import tax codes so invoices, estimates, and receipts sync with the same rates QBO expects.

From the QuickBooks page

After connecting, a yellow banner appears until tax codes are imported:

1. Click Import Tax Codes
2. Wait for the import to finish
3. The banner clears when at least one rate is mapped

From Sales Tax settings

You can also import or refresh from Sales Tax:

1. Open Sales Tax
2. Click Import Tax Codes or Refresh
3. QBO-synced rates show a sync indicator in the tax library

Per-location tax applies when multi-location is on. Secondary locations can copy tax from the primary profile before importing from their own QBO file.

See Sales Tax for zones, materials-only rules, and jurisdiction lookup.

---

Sync settings (entity toggles)

Open Sync Settings on the connected integration page. Changes sync automatically when records are created or updated in Dirt Face. Click Save after changing toggles.

Each toggle has a help icon with a short description. Summary:

Inventory tracking in QuickBooks (separate card)

If the inventory module is enabled, an Inventory Tracking card appears above Sync Settings.

• Track Inventory in QuickBooks Online pushes stock quantities from Dirt Face to QBO
• Enabling it forces Items sync on and locks that toggle
• We recommend keeping this off and using Dirt Face as your inventory source of truth. QBO lacks assemblies, multi-warehouse inventory, and automated adjustments. Use the help icon on that card for full detail.

What does not sync through these toggles

• Material COGS from job costing does not push separately. Material cost reaches QBO as Bills when purchase orders are received.
• Job profitability stays in Dirt Face. See Job costing.

---

Employee mapping (Time cards sync)

When Time cards (TimeActivity) is enabled, an Employee mapping section appears below Sync Settings.

Each Dirt Face team member must link to a QBO employee record before approved time can sync.

Map employees manually

1. Enable Time cards (TimeActivity) and save
2. In Employee mapping, pick a QBO employee from the dropdown for each Dirt Face user
3. Click Save

Use — Not mapped — to clear a link.

Match wizard

For bulk setup, click Match wizard:

• Dirt Face suggests matches by name and email
• Review high, medium, and low confidence suggestions
• Link existing QBO employees or create new ones in QBO from the wizard
• Apply all selections at once

You can also link employees when inviting or editing team members under Manage Team (QBO link section on the member form).

Approved timesheets post labor to Job costing in Dirt Face and optionally to QBO TimeActivity when mapped. Configure burdened labor rates under Timesheets settings.

---

Job mapping and job expenses

Jobs sync to QBO as sub-customers under the job's customer. This happens automatically when a job is synced (including historical sync). You do not map jobs manually on the integration page.

Job mapping is required when these toggles are on:

• Time cards (TimeActivity) (time tied to a job)
• Job expenses (purchases tied to a job sub-customer)

When Job expenses is enabled, choose the QBO expense account that receives those purchases in Job cost account mapping.

---

Historical sync

Use Historical Sync to push records created before you connected QBO.

1. Expand Historical Sync
2. Set Start Date (required) and optional End Date, or click All Time for roughly the last year through today
3. Select entity types: Customers, Invoices, Estimates, Payments, Jobs, Vendors, Components, Purchase Orders, Bills, Refunds
4. Click Sync

Progress shows per entity type (synced, errors, skipped). Large date ranges can take several minutes. New records after connect sync automatically without using historical sync.

---

Sync history

Sync History lists every sync attempt for the active location.

Reading the log

Each row shows:

• Entity name and type (customer, invoice, payment, etc.)
• Operation (push to QBO or pull from QBO)
• Status: success, failed, pending, or skipped
• Date and time

Expand a row for QBO ID, duration, trigger source (automatic, manual, retry, historical), who triggered it, and error details.

Filters and actions

• Filter by entity type or status
• Click Show Failed when failures need attention
• Refresh reloads the list

For failed rows:

• Retry reruns the sync when the error is retryable
• Force Retry appears after several failed retries for non-connection errors
• Dismiss removes the failure from the attention list

Use Dismiss all failed or dismiss connection/auth errors in bulk when failures are from an expired connection and you have already reconnected.

Connection errors usually require Reconnect on the integration page before retry succeeds.

For common fixes, see QuickBooks sync errors.

---

Recommended setup by business type

Estimating and invoicing only

Leave on: Customers, Estimates, Invoices, Payments, Receipts (if used).
Import tax codes. Leave Items, PO/Vendors, Time cards, and Job expenses off unless needed.

Inventory and POs

Add: Vendors, Purchase Orders.
Keep Items off unless accounting needs component detail on QBO invoices. Keep Track Inventory in QBO off unless your accountant specifically requires it.

Job costing with timesheets

Add: Time cards, map all employees, ensure jobs sync (historical or automatic).
Optional: Job expenses for out-of-pocket field costs.
Keep job profitability analysis in Dirt Face; use QBO for accounting and tax records.

---

Troubleshooting quick reference

Full guide: QuickBooks sync errors

---