QuickBooks Integration

Business Plus only Web App

The QuickBooks integration keeps your customer and vendor records in sync between Excavation Expert and QuickBooks Online, and produces import-ready files for pushing timecards and haul logs into QuickBooks Desktop for invoicing and payroll.

QuickBooks Integration is a Business Plus exclusive feature. Owner, Manager, and Bookkeeper roles can set it up and trigger syncs.

What gets synced

Record type	Direction	Notes
Customers	QB ↔ EE	Full two-way. QB customers come in automatically; EE manual customers push to QB on sync.
Vendors	QB ↔ EE	Same pattern as customers.
Timecards	EE → QB (file)	Download TSV, import via QB Desktop File → Utilities → Import.
Haul logs	EE → QB (file)	Same pattern, TSV + UTF-8 BOM for QB compatibility.
Invoices	EE → QB (API)	Push accepted bids / change orders as invoices.
Everything else	—	Equipment, materials, inventory, projects — not synced (EE-only).

Connecting QuickBooks Online

1. Go to Settings → App Integrations in the web app.
2. Find the QuickBooks card and click Connect to QuickBooks.
3. A popup window opens to Intuit’s OAuth screen. Sign in with the Intuit account that owns your company file.
4. Authorize Excavation Expert to access your company file. We request one scope: com.intuit.quickbooks.accounting.
5. The popup closes automatically on success, and the card shows “Connected” with your company name and realm ID.
6. First-time sync runs automatically in the background — existing QB customers and vendors populate the app’s Resources lists.

Popup blockers

If the OAuth popup doesn’t open, check your browser’s popup blocker for excavation.expert and allow it. The app shows a toast error if the popup was blocked.

Customer sync

Once connected, customer sync works in both directions:

QuickBooks → Excavation Expert (pull on sync):

• All active QB customers (Active = true) are imported on each sync.
• Each gets tagged with a small “QB” badge in the Resources → Customers list.
• Synced customer fields are read-only in Excavation Expert — edit them in QuickBooks, they update on the next sync.

Excavation Expert → QuickBooks (push on sync):

• Customers you add manually in EE (with source: 'manual') are pushed to QB on the next sync.
• Duplicates are checked by company name before create.
• Once pushed, the EE record picks up the qbId and flips to read-only.

Trigger a manual sync anytime from Resources → Customers → Sync with QuickBooks.

Vendor sync

Identical pattern to customer sync:

• QB vendors pulled in on sync, tagged with the QB badge, read-only in EE.
• Manual EE vendors pushed to QB on sync.
• Duplicate check by company name.

Trigger via Resources → Vendors → Sync with QuickBooks.

Timecard export to QB Desktop

Timecards export as a TSV file that QuickBooks Desktop can import directly:

1. Go to Timecards → Reports.
2. Apply your filters (pay period, specific personnel).
3. Click Export → QuickBooks.
4. A file like timesheet-export-2026-04-15.tsv downloads to your computer.
5. In QuickBooks Desktop: File → Utilities → Import → Timer Activities (or the import option that matches your QB version).
6. Point to the downloaded file. QB imports the entries as billable time.

Columns exported: Employee Name, Date, Project, Equipment, Hours, Work Performed, General Labor, Invoice ID, Status.

Haul log export to QB Desktop

Same flow, for haul logs:

1. Go to Haul Logs → Reports.
2. Filter to the period you want to bill.
3. Click Export → QuickBooks.
4. Download haul-log-quickbooks-2026-04-15.tsv.
5. Import via File → Utilities → Import in QuickBooks Desktop.

Columns: Project Name, Date, Material Name, Quantity, Unit, Hours, Direction, Source, Destination, Driver Name, Truck Name, Price Per Unit, Total Cost, Invoice ID, Lock Status.

The file includes a UTF-8 BOM for QuickBooks compatibility.

What’s stored about your QB connection

Under the hood, connecting creates an integration record on your company profile with:

• Realm ID: your QuickBooks company/file identifier.
• Access token + refresh token: rotated automatically. We never ask you to re-authenticate once connected, unless the refresh token expires (rare — QB’s refresh tokens are long-lived).
• Last sync timestamp: visible on the integration card.

Troubleshooting

“Sync failed” toast: usually a transient token refresh. Click Sync with QuickBooks again — the app refreshes the token on retry.

“Requires reconnect”: the refresh token expired. Disconnect and reconnect from Settings → App Integrations.

QB customer not showing up in EE: confirm it’s marked Active in QuickBooks. Inactive customers aren’t pulled.

EE manual customer not pushing to QB: check that company name doesn’t duplicate an existing QB customer. The app skips duplicates silently.

Disconnecting

1. Go to Settings → App Integrations.
2. Click Disconnect on the QuickBooks card.
3. Tokens are cleared from the server. No further syncs happen.
4. Existing synced records stay in place — you don’t lose history — but they’re no longer kept in sync with QB.

Reconnect at any time to resume syncing.

Next steps

Customers Where the QB customer sync lands.

Vendors Same pattern for vendor sync.

Timecards Export timecards as QuickBooks-ready TSV.

Haul Logs Export haul logs for QB invoicing.