QuickBooks Online Integration

Written By Timothy Murenzi

Last updated 9 days ago

Push your Estimates, Invoices, and Purchase Orders from Workroom into QuickBooks Online so QBO handles the books while Workroom stays the source of truth for the documents themselves. Customers, vendors, line items, taxes, and accounts all flow over the OAuth connection — no copy-paste, no CSV exports.

What QBO sync does (and doesn't do)

Does:

  • Push Estimates / Invoices / Purchase Orders one-way from Workroom → QBO

  • Sync the Workroom client list with QBO customers

  • Sync the Workroom vendor list with QBO vendors

  • Map your tax codes per-line so each line lands with the right TAX / NON flag

  • Pull a read-only Profit + Loss view back into Workroom

Doesn't:

  • Push or pull payments — payment recording stays in QBO

  • Pull invoices created in QBO back to Workroom

  • Two-way sync of customer / vendor edits — Workroom is the source of truth there

  • Push retainers / credits as separate QBO items

  • Sync products / services catalog two-way

Where to find it

QBO surfaces are spread across a few places:

  • Settings → Apps → QuickBooks Online — connect / disconnect the account

  • Settings → Finances → QuickBooks — account + tax mapping (visible once connected)

  • Finances → Sync Center — push history, retry queue, errors

  • Reports → QuickBooks P&L — read-only Profit + Loss pulled live from QBO

Each one only shows up after the connect step is complete.

Section 1 · Connecting QuickBooks

  1. Open Settings → Apps.

  2. Find the QuickBooks Online tile and click Connect.

  3. Sign into Intuit when the OAuth popup opens.

  4. Pick the company file you want Workroom to sync into.

  5. Approve the requested scopes — Workroom reads your chart of accounts, customers, vendors, items, and tax codes, and writes Estimates / Invoices / POs.

  6. You'll bounce back to Workroom with a green "Connected" badge on the tile.

Workroom auto-detects whether the connection is sandbox vs production by probing the realm. There's nothing to configure manually — if you connected to a sandbox file, the integration will know and won't push to your live books.

To disconnect: Settings → Apps → QuickBooks Online → Disconnect. Past pushed documents stay in QBO; new pushes stop immediately.

Section 2 · Account Mapping

Before your first push, tell Workroom which QBO accounts each part of a document belongs to.

Settings → Finances → QuickBooks

Income accounts:

  • Default Income Account — where Estimate / Invoice line revenue posts (typically Design Services or Sales of Product Income)

  • Optional per-category — override the default for specific product categories (e.g. Furniture Income, Lighting Income)

Expense accounts:

  • Default Expense Account — where PO purchases post (typically Cost of Goods Sold or Purchases)

  • Optional per-vendor — override the default for specific vendors

Deposit / liability accounts:

  • Retainer / Deposit Liability — where client retainers land. Should be a Liability type in QBO, not income.

  • Sales Tax Payable — usually QBO sets this up automatically

If you skip the mapping step, pushes will fail at the line level with an "account not specified" error from QBO's side.

Section 3 · Tax Mapping

Pair your Workroom tax codes with QBO tax codes so every line lands with the correct tax classification.

Settings → Finances → QuickBooks → Tax mapping

For non-Canadian accounts:

  • Map your Workroom Sales Tax % to a single QBO tax code (usually Out of scope, Tax, or a named state rate).

For Canadian accounts:

  • One row per Workroom Tax Code (BC GST+PST, ON HST, GST only, Exempt).

  • Pair each with the matching QBO tax code (e.g. HST ON, GST/PST BC).

  • Workroom pushes per-line TaxCodeRef TAX for taxed lines and TaxCodeRef NON for exempt — the gating is per-line, not per-document.

Workroom only pushes the TAX/NON gate, not the QBO tax code ID itself, in the current sync. The per-line gate plus your document-level tax code is enough for QBO to compute the right tax — but a future enhancement will push the ID directly.

Section 4 · Customers (Clients)

The first time you push an Estimate / Invoice for a client, Workroom looks for a matching QBO customer.

Match logic:

  1. Match by client name (case-insensitive, trimmed)

  2. If no match, create a new QBO customer using:

    • Name from the Workroom client's clientInformation.name

    • Email, phone, billing address from the Workroom client record

Once matched / created, Workroom remembers the QBO customer ID on the client record. Future pushes for the same client skip the lookup.

Customer name gotcha: Workroom uses clientInformation.name — not fullName — for the QBO push. If a client shows up in QBO without their full name, check that field on the Workroom client record.

Section 5 · Vendors

Same flow as customers, but for POs.

Match logic:

  1. Match by vendor name

  2. If no match, create a new QBO vendor using the Workroom vendor record

Vendors also remember their QBO vendor ID after first match so subsequent PO pushes skip the lookup.

Section 6 · Pushing Documents

Each document type has a Push to QuickBooks action.

From the Estimates / Invoices / Purchase Orders list:

  • Open the document

  • Click ⋯ (action menu) → Push to QuickBooks

  • Wait for the green confirmation or red error

From the Sync Center:

  • View queued + retried pushes

  • Bulk-push all approved documents

  • Retry any failed pushes after fixing the root cause

What gets pushed:

  • Document header (number, dates, currency)

  • Customer / vendor ref

  • Each line item: description, quantity, rate, amount, tax flag, income/expense account

  • Totals (sub-total, tax, total) — QBO recomputes from the lines as a sanity check

What doesn't get pushed:

  • Workroom-specific fields (markup %, vendor discount, internal notes)

  • File attachments

  • Multi-currency conversions — push currency must match the QBO company's home currency

Section 7 · Sync Center

Finances → Sync Center

Your audit log + queue for everything QBO-related.

What you see:

  • Recent pushes — chronological list of every push attempt, success or failure

  • Push status — pushed, failed, queued

  • Error reason — when failed, the actual QBO error message (e.g. "Account not specified for line item")

  • Retry — re-attempt a failed push after fixing the underlying issue

  • Health card — at-a-glance count of failed pushes that need attention

This is where you live during month-end close to catch any drift before reconciling.

Section 8 · QuickBooks P&L (read-only)

Reports → QuickBooks P&L

A live-pulled Profit + Loss view from your QBO file, displayed inside Workroom.

  • Pulls fresh on every open — no cache

  • Shows the same line items as the QBO P&L report

  • Date-range picker on the page

  • Read-only — to edit, jump into QBO directly via the link at the top of the page

Useful when you want a quick financial snapshot without leaving Workroom and switching tabs.

Good to know

  • One-way sync. Treat Workroom as the document source of truth. Edit Estimates / Invoices / POs in Workroom and re-push; don't edit on the QBO side and expect Workroom to pick it up.

  • Push only after the document is final. Pushing a draft Estimate that you'll edit later creates the QBO record at the draft state and you'll have to update it manually in QBO afterwards. Best practice: finalize → push.

  • Connection environment is auto-detected. Sandbox / production self-heals when Workroom probes the realm. No setting to flip.

  • Tokens stay server-side. OAuth tokens live on the Workroom backend, refreshed automatically. You don't need to manage anything.

  • Disconnect is non-destructive. Disconnecting QBO doesn't delete anything in QBO or Workroom. Re-connect at any time and the customer / vendor ID mappings come back.

Troubleshooting

"Push failed: Account not specified for line item." Open Settings → Finances → QuickBooks and confirm Default Income / Expense accounts are set. The push payload requires this on every line.

"Push failed: Customer not found." The client's Client information doesn't match any QBO customer AND Workroom couldn't create one. Check the client record — usually a missing email or address blocks customer creation. Fill those in and retry.

"Push failed: Tax code mismatch." Tax mapping isn't set up, or the document is using a Workroom tax code that doesn't have a QBO counterpart. Open Settings → Finances → QuickBooks → Tax mapping and pair it.

"The QBO P&L page says 'No data'." The OAuth token expired silently. Disconnect + reconnect QuickBooks from Settings → Apps. Tokens auto-refresh in most cases, but a long-idle account can fall outside the refresh window.

"My push went through but the totals are off by a few cents." Per-line rounding. Workroom rounds at the document subtotal level; QBO rounds at the line level. Differences under $0.05 per line are normal. Recompute the QBO total against the Workroom total and adjust manually if needed.

"I pushed to the wrong company file." Disconnect from Settings → Apps, then reconnect and pick the correct company file in the Intuit chooser. Past pushes to the wrong file stay in that file — delete them from inside QBO.

"I see two of the same client in QBO." Workroom's match-by-name is case-insensitive + trimmed, but small name differences (Smith LLC vs Smith, LLC) won't match. Open the Workroom client and rename to exactly match the QBO customer, then re-push. Delete the duplicate from QBO afterwards.