How do I connect QuickBooks AR with idempotent invoice sync?

Loopfour's QuickBooks integration keys invoice sync off DocNumber, the same invoice number field QuickBooks itself exposes through Custom transaction numbers. Looking an invoice up by DocNumber before writing lets a rerun update the existing invoice instead of creating a duplicate — even if the workflow has lost track of QuickBooks' own internal invoice Id.

By Zuny Fester, Head of Operations and Marketing

Reviewed by Zuny Fester

Published September 14, 2026Last reviewed September 14, 2026Editorial policy

Part of the finance integrations guide.

Key field	DocNumber — QuickBooks' customer-facing invoice number
Mechanism	Look up by DocNumber first (findInvoiceByDocNumber), then create or update accordingly (upsertInvoiceByDocNumber)
Prerequisite	Custom transaction numbers enabled in QuickBooks, so DocNumber is set deliberately rather than auto-assigned
Why it matters	A rerun over the same invoice updates it in place instead of creating a second one

Why DocNumber, and not QuickBooks' internal Id

Every QuickBooks invoice has an internal Id assigned by QuickBooks on creation — reliable as a lookup key, but only if the calling system stored it. If a workflow's own record of that Id is lost (a crashed run before the Id was persisted, a partial state restore), there's no way back to "is this invoice already there" without something the caller controls. DocNumber is that something: it's the invoice number QuickBooks lets a business set deliberately, through the Custom transaction numbers setting in Sales form content, rather than always auto-incrementing it.

How the lookup-then-write pattern works

Loopfour's integration exposes a dedicated findInvoiceByDocNumber action, and a combined upsertInvoiceByDocNumber action that probes for an existing invoice with that DocNumber before deciding whether to create a new one or update the one it found. Internally, this is what makes a second run over the same invoice — after a retry, a redeploy, or a scheduled resync — update the existing QuickBooks invoice rather than duplicate it, as long as the caller keeps sending the same DocNumber for the same invoice every time.

What this depends on getting right upstream

This pattern only works if DocNumber is actually stable and unique per logical invoice on the sending side. QuickBooks' own support guidance describes enabling Custom transaction numbers specifically so a business can set and control its own numbering — without it, QuickBooks may auto-assign numbers that a caller doesn't control, which breaks the whole premise of looking an invoice up by a number the caller chose. Before relying on DocNumber-based sync, confirm Custom transaction numbers is actually turned on for the connected QuickBooks company.

Next step

Map the finance workflow with the most exposure and prove the automation path.

Bring the invoice, contract, payment reconciliation, or customer finance workflow you have to defend at audit. Loopfour can map the trigger, controls, integrations, and approval loop.

Book a workflow review

Worked example

A retried sync that updates instead of duplicating

A workflow creates invoice INV-4821 in QuickBooks via upsertInvoiceByDocNumber. The call succeeds and QuickBooks returns internal Id 9284, but the workflow crashes before persisting that Id to its own database. On the next scheduled run, the workflow has no record that INV-4821 was ever created — all it has is the DocNumber from the source system. It calls upsertInvoiceByDocNumber again with docNumber: 'INV-4821'. The action's internal probe finds the existing invoice (Id 9284) by DocNumber first, and updates that record instead of creating a second INV-4821 — the workflow never needed to know Id 9284 existed.

Frequently Asked Questions

QuickBooks controls invoice numbering instead of the caller, which breaks the premise of looking an invoice up by a DocNumber the workflow chose — turn it on before relying on this pattern.

No — they solve different problems. Custom transaction numbers with a DocNumber-based upsert is about making Loopfour's own sync reruns safe; QuickBooks' duplicate-invoice-number detection is a separate, user-facing safeguard in the QuickBooks UI itself.

Already covered by Phase 1's diagnostic pages on reading a QuickBooks AR aging report and automating dunning reminders — this page is specifically about the connection/sync mechanism, not aging or collections behavior.

Sources

Topic

AR & Collections

Accounts receivable is the money customers owe a business for goods or services already delivered on credit — a current asset on the balance sheet until it's collected. AR and collections, as a practi…

Definition

What is an AR aging report and how do I read it?

An AR aging report lists every open invoice grouped by how long it's been outstanding — current, 1-30, 31-60, 61-90, and 90+ days past due. Read it by tracking the bucket distribution over time, not just the total; a shrinking current bucket and growing 90+ bucket signal a collections problem before it shows up in a blended DSO figure.

How-to

How do I automate dunning and collections reminders?

Schedule reminders relative to the due date (a few days before, then at set intervals after), with escalating tone and channel, and add a suppression check before each send confirming the invoice is still genuinely open and undisputed. Most accounting systems support scheduling this natively; the suppression check is what prevents the most damaging automation failure.

Topic

Integrations

Every finance automation vendor publishes an integrations page: a grid of logos, a claim of "seamless" connectivity, and not much else. That page answers a marketing question — does this vendor touch…