Skip to main content

​
Enable and use the QuickBooks connector

The QuickBooks connector ties the job you run in XBuild to the books you keep in QuickBooks Online. Link a project to its QuickBooks customer once, and the customer’s estimates and invoices file themselves into the project’s Documents, job-site photos can be shared onto the paperwork, and deposits collected in XBuild post back to QuickBooks — no re-keying, no emailing files to the office. You must be logged into XBuild as an Administrator to connect QuickBooks. Connectors require an XBuild Pro Subscription Plan or greater. The connector works in both the XBuild web app and the mobile app.

​
Why connect QuickBooks to XBuild?

Your jobs run in XBuild and your books live in QuickBooks. This connector keeps the two in step — financial paperwork lands on the project, and job evidence lands on the books, without anyone re-entering data.
  • Estimates and invoices where the crew looks: every estimate or invoice on a linked customer lands in the project’s Documents automatically, so nobody opens QuickBooks to check what’s been quoted or billed.
  • Estimates and invoices without leaving XBuild: sign a proposal and XBuild creates the QuickBooks estimate for you; generate the invoice when you’re ready, then send it to your customer from QuickBooks. XBuild matches your line items to your QuickBooks products and only asks you to confirm the ones it isn’t sure about.
  • Photos on the paperwork: share job-site photos onto a QuickBooks estimate, invoice, or the customer record — proof-of-work attached to the books without email round-trips.
  • Deposits that reconcile themselves: a deposit collected in XBuild posts to the linked customer in QuickBooks — applied to that version’s XBuild invoice when one exists (up to its open balance), or left unapplied for your bookkeeper when it doesn’t.
  • Contacts that stay current in both systems: with two-way contact sync on, a correction to a customer’s name, email, phone, or billing address in either system flows to the other — no stale records, and no silent overwrites when both sides changed.
  • Answers in chat: ask the AI “has this job been invoiced?” or “is the invoice paid?” and get the current state from QuickBooks.

​
1. Connect Your QuickBooks Online Account

  1. Navigate to Settings → Connectors → QuickBooks.
  2. Click + Add connection, then Sign in with QuickBooks. XBuild uses Intuit’s secure OAuth — we never see or store your password.
  3. Log in to Intuit in the secure window, review the requested permissions, and click Authorize. If your Intuit login has more than one company, pick the company to connect.
  4. Optionally set a Display name for the connection. XBuild supports one QuickBooks company per workspace.
Once connected, open the Configuration section. Its first sub-section, Documents & payments, holds two workspace defaults, both on by default:
  • File estimates & invoices to the project — file PDFs from QuickBooks into linked projects’ Documents.
  • Post collected deposits to QuickBooks — post XBuild-collected deposits back to QuickBooks.
Each capability below hangs off a one-time link between an XBuild project and a QuickBooks customer. While linking, you can also pull the customer’s existing QuickBooks files into the project.

​
Open the QuickBooks Picker

Open the project’s chat and click the + menu, then choose QuickBooks. This works on a brand-new chat too — the customer you pick and any files you select ride along with your first message. You can also start a new project from a QuickBooks customer: create a project, choose Import from Connectors, then QuickBooks, and XBuild creates the project linked to that customer with the customer’s name and address filled in.

​
Choose a Customer

Search your QuickBooks customers by name — the picker matches the display name as it appears in QuickBooks. Each row shows the name and address so you can tell similar customers apart, and sub-customers show which parent they belong to. You can link at either level. A QuickBooks customer links to one XBuild project (and vice versa), so customers that are already linked are marked in the list. If the customer you need is linked to another project, XBuild shows you which one and offers to move the link — or, if both jobs are real work for the same customer, create a sub-customer for the new job in QuickBooks and link to that instead. If the person isn’t in QuickBooks yet and two-way contact sync is on, the picker also offers Create customer in QuickBooks from [contact] — see Keep contacts and customers in sync.

​
Select Files and Photos

After picking the customer, XBuild lists the attachments already stored in QuickBooks — both on the customer record itself and on the customer’s recent estimates and invoices — split into Files and Photos tabs with select-all controls. Select what’s useful for the job and confirm; XBuild imports your selection into the project. Re-importing later won’t create duplicates. A confirmation card appears in the project chat. XBuild fills in the project’s client name and address from the customer record, and writes a link back to the XBuild project into the customer’s Notes in QuickBooks, so anyone working in the books can jump straight to the job. You can unlink at any time from the same menu. Unlinking stops future syncing — documents already filed stay on the project. Tip: to import more QuickBooks files later, open the + menu again — the linked customer card lets you re-open the file picker without changing the link.

​
3. Estimates and Invoices in Project Documents

With a project linked and File estimates & invoices to the project on, XBuild files the customer’s existing estimates and invoices right away, then keeps up as things change in QuickBooks:
  • New or revised estimates and invoices appear in the project’s Documents, grouped under Financial and tagged Estimate or Invoice. A revised document replaces the previous version in the list — including when a payment changes the invoice’s balance, so you always see the current state.
  • Voiding or deleting a document in QuickBooks doesn’t make it vanish in XBuild — the filed copy stays, labeled Voided.
  • The linked-customer card in the chat + menu shows Estimate attached / Invoice attached once documents have synced.

​
4. Push Estimates and Invoices from XBuild to QuickBooks

Beyond filing what already exists in QuickBooks, XBuild can create the estimate and invoice in QuickBooks for you — the reverse direction. An Administrator sets this up once for the workspace under Settings → Connectors → QuickBooks → Configuration → Estimates & invoices with two separate switches:
  • Push estimates & invoices to QuickBooks — turns invoicing on and reveals how line items map to your QuickBooks products. This alone enables the estimate-on-signing push.
  • Enable invoice creation from pushed estimates — off by default. Turn it on to let Administrators generate invoices; the Generate action does not appear until it’s on. Estimates still push on signing regardless of this switch.
  • Estimate on signing: when a proposal is signed, XBuild pushes its estimate to QuickBooks automatically as an Estimate on the linked customer.
  • Invoice on demand: with Enable invoice creation from pushed estimates on, an Administrator generates the QuickBooks invoice from a signed proposal; the invoice is linked to the estimate it came from. Invoices can only be generated for proposals that have been signed, and each signed proposal version maps to its own estimate and invoice.
On plans with the project Financials tab, there’s a second way to invoice into QuickBooks: Invoice with QuickBooks on the Financials tab. It bills what’s ready on the job — completed trades, authorized change orders, the deposit — as one QuickBooks invoice at a time, and it isn’t closed by an earlier paid invoice. It’s for Administrators, and needs a signed contract, Push estimates & invoices to QuickBooks turned on, and a linked customer. See Customer invoices. The rest of this section covers invoices generated from a proposal.

​
Generating an invoice, then sending it

When you generate an invoice, XBuild first shows a quick review of exactly what will go to QuickBooks — the customer, the source estimate, and every line item — so you can check it before anything is created. Confirm, and XBuild creates the invoice on the linked customer in QuickBooks. XBuild creates the invoice — it doesn’t email it to your customer. Sending the invoice is a deliberate step you take in QuickBooks when you’re ready. Until you do, XBuild shows the invoice as created but not yet sent — in the project chat’s QuickBooks card and under View invoice — and reminds you to send it from QuickBooks. You can reopen a generated invoice at any time — View invoice, on the proposal header or the project’s Overview, shows the items that were sent to QuickBooks and where the invoice stands: being created, created and awaiting sending, sent to the customer, or paid. Once you send the invoice from QuickBooks, the proposal’s status advances to Invoiced; when the invoice is paid, it becomes Invoice Paid.

​
How line items map to QuickBooks products

Every estimate or invoice line must reference a product in your QuickBooks item catalog. XBuild matches your XBuild line items to your QuickBooks products for you — using name, price, and category — and remembers every mapping you confirm, so setup is a quick review rather than a hand-built table. The How line items map to QuickBooks products setting controls what happens when a push needs a product that isn’t confirmed yet:
  • Automatic (default): XBuild pushes the estimate straight through when every line already maps to a product you’ve confirmed before. If a line would need a new product, or uses a suggested match you haven’t confirmed yet, XBuild pauses just those lines for review first — it never silently creates or adopts a product you haven’t approved.
  • Review every estimate: XBuild pauses every push so you can confirm or remap each line before the estimate is created — including lines that are already mapped.
When a push is paused for review, it waits in a needs review state and the project chat shows a Review & confirm items action. Confirm or remap each line and submit; XBuild creates the estimate against exactly those products and remembers your choices. In Automatic mode those confirmed lines then push straight through on later estimates; Review every estimate still pauses every push, even for lines you’ve already confirmed. The fallback income account is only needed when XBuild has to create a new QuickBooks product — if a line requires a new product and no fallback income account is configured, that push is held with that reason until an Administrator sets one under Configuration → Estimates & invoices → Income accounts.

​
Invoice status, and when invoicing closes

Once an invoice exists, XBuild keeps its status in step with QuickBooks and shows it on the proposal and the project:
  • Per proposal version: each signed version shows its own invoice status — open, partially paid, paid, overdue, or voided — read from the invoice’s balance and due date in QuickBooks.
  • At the project level (while unpaid): until an invoice is paid, the project reflects the most recent invoice’s status at a glance (a newer unpaid invoice supersedes an older one, so you can see what still needs collecting).
  • Paid takes precedence and closes proposal invoicing: once any invoice generated from a proposal is paid, that becomes the project’s status and stays there — this overrides the most-recent rule above (even if a newer unpaid invoice exists), and generating invoices from proposals is closed for the whole project. You can generate multiple invoices across signed versions, but as soon as one is paid, XBuild stops offering to generate more from proposals. To bill more after that — a change order, say — use Invoice with QuickBooks on the Financials tab, which isn’t affected (see Customer invoices). Pick only the new items there: an invoice generated from a proposal doesn’t count against the trades it billed, so those trades still show as ready to bill, and picking them invoices the customer for the same work twice.
You can also filter the projects list by invoice status — open Filters on the Projects page and pick Invoiced or Paid to see exactly the projects whose badge shows that state, instead of scanning every project.

​
Invoicing notifications

XBuild emails your invoicing contact at the key moments of the invoicing lifecycle, so the back office doesn’t have to watch the connector:
  • when an estimate is created in QuickBooks,
  • when line items need review before an estimate can be created,
  • when an invoice is created in QuickBooks,
  • when an invoice is paid.
Set the recipient under Settings → Connectors → QuickBooks → Configuration → Estimates & invoices → Invoicing notifications contact. Leave it blank to send these to the project’s sales rep instead.

​
5. Share Job-Site Photos to QuickBooks

Photos never sync to QuickBooks on their own — you choose what the office sees.
  1. From the project’s photos (or the album in the mobile app), select one or more photos.
  2. Choose Share to QuickBooks.
  3. Pick the target: the linked customer record, or a specific estimate or invoice on that customer. If the customer has no estimates or invoices yet, the customer record is the only option.
  4. Confirm. XBuild uploads the photos as attachments on the chosen record and remembers what’s been shared, so re-sharing the same photos to the same target won’t create duplicates.

​
6. Deposits Post Back to QuickBooks

When a homeowner pays a deposit on a linked project (and Post collected deposits to QuickBooks is on), XBuild posts it to QuickBooks under the linked customer, with the Stripe payment reference attached.
  • No XBuild invoice for that signed version yet: the deposit posts as an unapplied payment. Your bookkeeper applies it on their terms — XBuild never guesses at a match. (If you later generate the invoice for that version through XBuild, the deposit is applied to it automatically.)
  • An XBuild invoice already exists for that version: the deposit is applied to that invoice, up to its open balance. If the deposit is larger than the balance, only the balance is applied and the remainder stays as an unapplied credit on the customer — never overpaying the invoice.
Auto-apply only happens for invoices XBuild generated for that proposal version; if you post deposits without XBuild invoicing, deposits always post unapplied. If QuickBooks rejects the posting — most commonly a closed accounting period or missing permissions — XBuild holds the deposit and flags it on the project instead of posting something wrong. Fix the cause in QuickBooks, then an Administrator can use Retry on the project to post it again. Company admins also receive a Sync failures notification when this happens — see Notifications.

​
7. Keep Contacts and Customers in Sync

Two-way contact sync keeps a person’s details matched between their XBuild contact and their linked QuickBooks customer: name, email, phone, and billing address. It’s off by default — an Administrator turns it on under Settings → Connectors → QuickBooks → Configuration → Contact sync. Turning it on does a one-time pass over your existing linked customers: each one is matched to the contact already on its project, to a directory contact with the same email or phone, or — when nothing matches — to a new contact created from the customer. Details that already differ between the two systems are never changed silently: they show up as conflicts to resolve, and anything typed on the project’s client details is kept. From then on:
  • Linking a customer also links the person. When you link a project to a QuickBooks customer, XBuild finds the matching contact in your directory — or creates one from the customer — and makes it the project’s contact. If the project already has a different contact, the web app asks which you want: Link & make primary switches the project’s contact to the linked customer, Link only keeps your current one — the customer stays linked and syncing either way (the mobile app keeps your current contact). Sub-customers are job-specific and are deliberately left out of contact sync.
  • Edits flow both ways. Change a synced detail on the contact in XBuild and the QuickBooks customer updates; a bookkeeper’s correction in QuickBooks updates the XBuild contact (and the project’s client details with it).
  • Conflicts ask, never overwrite. If the same detail was changed in both systems, XBuild flags it on the contact’s page and shows both values with a Use XBuild / Use QuickBooks choice. That field stops syncing until you choose — nothing is overwritten silently.
  • Deletes never cross over. Making a customer inactive in QuickBooks stops the sync but leaves the XBuild contact untouched; deleting a contact in XBuild never touches the QuickBooks customer. Books records and CRM records are each cleaned up on their own terms.
  • You see what the bookkeeper did. When a linked customer is merged, deleted, or made inactive in QuickBooks, it shows up under Settings → Connectors → QuickBooks → Sync issues: a merge is handled automatically (the link follows the surviving customer — the entry is just a heads-up), while a deleted or inactive customer pauses that project’s syncing until you relink it from the project page — or until the customer is made active again in QuickBooks, which resumes it on its own.
  • Turning the sync off is warned, not silent. Switching the toggle off shows a heads-up first: from that point, contact edits in XBuild and customer edits in QuickBooks drift apart, and corrections have to be made in both systems by hand until it’s turned back on.

​
Create a QuickBooks customer from an XBuild contact

When a person exists as an XBuild contact but not in QuickBooks yet, you don’t have to re-key them. With contact sync on, the places you pick a QuickBooks customer on the web — the project’s link flow, the chat + menu (existing and new chats), and the create-project Import from Connectors step — also offer Create customer in QuickBooks. When the project already has a contact, XBuild offers to create from them by name; in a new chat or the create-project step, you pick which contact to create from. The mobile app works the same way in its QuickBooks link flow: a project chat creates from the project’s contact, and a new chat lets you pick the contact first. Before creating anything, XBuild searches QuickBooks for customers with the same name or email and offers them first, so you link the existing record instead of creating a duplicate. Confirm the create and XBuild makes the customer from the contact’s name, email, phone, and billing address; the pair starts syncing once the customer is linked to a project. One thing to know in the chat flows: the customer is created in QuickBooks the moment you confirm — the button says so — even though the project itself links when you send the message. If you change your mind and discard the pick, the customer remains in QuickBooks (nothing is billed; it’s just a customer record your bookkeeper can deactivate — your XBuild contact is untouched either way). Tip: QuickBooks requires customer names to be unique. If the name is already taken, XBuild tells you instead of creating a duplicate — link the existing customer, or rename one side.

​
8. Ask the AI About Invoicing Status

With a project linked, the project chat can answer read-only questions like “has this job been invoiced?”, “is the invoice paid?”, or “what’s been quoted?” — from the synced QuickBooks records, refreshed automatically when they’re stale.

​
9. Disconnect

An Administrator can disconnect from Settings → Connectors → QuickBooks using the X on the connection row. Disconnecting revokes XBuild’s access with Intuit and clears the workspace defaults. Documents already filed into projects are retained, and project links are kept — reconnecting the same company resumes syncing without re-linking. If your organization has multiple locations connected to the same QuickBooks company, note that Intuit revokes the authorization for all of them together: disconnecting QuickBooks from one location disconnects every location that shares that company.

​
10. Troubleshooting Common Issues

  • I don’t see QuickBooks in the + menu or Settings. QuickBooks requires a Pro plan or greater. Contact XBuild Support if you believe it should be available.
  • I can’t find the customer when linking. The picker searches active QuickBooks customers by display name. Check the spelling as it appears in QuickBooks, and confirm the customer isn’t inactive.
  • The customer I want is already linked to another project. A QuickBooks customer links to one project at a time. The link dialog shows the current project and offers to move the link — moving stops syncing on the old project but keeps its filed documents. For a second job with the same customer, create a sub-customer in QuickBooks and link to that.
  • A file I expected isn’t in the link picker. The picker lists attachments on the customer record and on the customer’s most recent estimates and invoices. Attachments on older transactions may not appear — attach them to the customer record in QuickBooks to make them available.
  • An estimate or invoice isn’t showing up in Documents. Confirm the project is linked to the right customer (or sub-customer — documents on a sub-customer sync to the project linked to that sub-customer) and that File estimates & invoices to the project is on under the connector’s Configuration → Documents & payments.
  • A deposit shows as held. QuickBooks refused the posting — usually a closed accounting period or a permissions change. Fix the cause in QuickBooks, then an Administrator clicks Retry on the project. XBuild never posts a guessed or mismatched transaction.
  • I can’t generate an invoice — the button never appears. Invoice generation is off until an Administrator turns on Enable invoice creation from pushed estimates under Settings → Connectors → QuickBooks → Configuration → Estimates & invoices (it’s off by default, and separate from the Push estimates & invoices to QuickBooks switch). Confirm both are on.
  • The Generate invoice button is gone. After you generate an invoice for a version, its Generate invoice button is replaced by View invoice — open that to see the items sent to QuickBooks, the invoice’s status, and a reminder to send it from QuickBooks if you haven’t. Separately, once any invoice generated from a proposal has been paid, generating more from proposals is closed for the project and it shows as paid. To bill more, such as a change order, use Invoice with QuickBooks on the Financials tab.
  • My estimate is waiting for item review. With item handling set to Automatic, XBuild pauses a push when a line needs a new QuickBooks product or a match you haven’t confirmed; with Review every estimate, it pauses every push. Open the Review & confirm items action in the project chat, confirm or remap each line, and submit — the estimate is then created. In Automatic mode confirmed lines push straight through next time; Review every estimate keeps pausing every push, even for lines you’ve already confirmed.
  • An estimate push is held for a fallback account. Item provisioning needs a fallback income account. An Administrator sets one under Settings → Connectors → QuickBooks → Configuration → Estimates & invoices → Income accounts, then retries.
  • Contact edits aren’t reaching QuickBooks. Check that Two-way contact sync is on under Configuration → Contact sync, and that the customer is still active in QuickBooks — an inactive customer pauses its sync (and appears under Sync issues with a pointer to the project to relink). If the contact’s page shows a conflict, the disputed field waits for your Use XBuild / Use QuickBooks choice; if it shows a held sync error, fix the cause and an Administrator can retry from the connector’s Sync issues list.
  • I created a customer from chat but never sent the message. The customer was created in QuickBooks the moment you confirmed — that’s what the button says — and it’s still there. Nothing is billed or linked, and your XBuild contact is unchanged; link the customer to a project later, or have your bookkeeper deactivate it if it was a mistake. XBuild remembers the pairing, so creating from that contact again offers the existing customer instead of a duplicate.
  • “This name is already used in QuickBooks.” QuickBooks requires customer display names to be unique per company. Rename one side, or — when creating a customer from a contact — link the existing QuickBooks customer XBuild offered instead.
  • I’m being asked to choose between an XBuild and a QuickBooks value. The same detail was edited in both systems since the last sync, so neither side wins automatically. Pick the value to keep on the contact’s page; syncing for that field resumes immediately.
  • We disconnected and reconnected — did we lose anything? No. Filed documents stay on their projects, and project links are kept — syncing resumes automatically once the same company is reconnected.
For further technical assistance, contact Intuit QuickBooks Support via https://help.quickbooks.intuit.com. For XBuild-side issues, contact XBuild Support at support@x.build.