Accounting & Payments Integrations — QuickBooks & Stripe

The Accounting tab of the Integrations page is where you connect Breeze to the tools that handle your money: QuickBooks Online for your books, and Stripe for collecting card payments online. Open it at Integrations → Accounting.

Note

Accounting and payment integrations are partner-account only. They’re set up once for your practice, not per customer. If you sign in with an organization (customer) account, the tab shows a message that the integration is available to partner accounts and there’s nothing to configure.

The tab has two sub-tabs:

• QuickBooks — connect QuickBooks Online, choose how invoices push, and import your existing customers. Deep link: /integrations#quickbooks.
• Payments — connect your Stripe account so customers can pay invoices by card. Deep link: /integrations#stripe.

---

QuickBooks Online

QuickBooks Online connects through Intuit’s standard OAuth consent flow. Once connected, Breeze can push your issued invoices to your books and pull your existing QuickBooks customers into Breeze.

Connecting QuickBooks

1. Open Integrations → Accounting and select the QuickBooks sub-tab.
2. Click Connect to QuickBooks. Breeze hands you off with a full-page redirect to Intuit’s consent screen.
3. Sign in to Intuit and authorize Breeze. Approving returns you to the Accounting tab with the connection established, and a confirmation toast appears.
4. The panel now shows the connection status, the connected environment (sandbox or production), and when it was connected.

Note

Connecting and disconnecting QuickBooks are MFA-gated — you may be prompted to complete multi-factor authentication before the action goes through.

What syncs

Item	Direction	Notes
Customers	QuickBooks → Breeze	Import your existing QuickBooks customers as Breeze organizations (see below).
Invoices	Breeze → QuickBooks	Issued invoices push to QuickBooks, either automatically or manually (your choice).
Payments	QuickBooks → Breeze	Payments recorded in QuickBooks against a pushed invoice mirror back into Breeze (see Payment pull-back below). Pushing a Breeze-recorded payment out to QuickBooks is not yet supported.

Invoice push mode

On the connected panel, choose how issued invoices reach QuickBooks:

• Automatic (on issue) — an invoice pushes to QuickBooks the moment you issue it.
• Manual — invoices are held so you push them on your own schedule.

You can switch between the two at any time; the change is saved immediately. Changing the mode requires the Invoices: write permission.

Only an invoice that has been issued can push: sent, partially paid, overdue, and paid invoices are all eligible. Drafts and voided invoices are never pushed.

Invoice sync status

Each pushed invoice carries one of these statuses, shown on the invoice detail page:

Status	Meaning
Pending	Queued to push, or a push is in flight.
Synced	Pushed successfully and QuickBooks’ totals match Breeze’s.
Synced (tax variance)	Pushed successfully, but QuickBooks computed a tax total more than 1¢ different from Breeze’s — usually because the QuickBooks customer or item has its own tax settings that override Breeze’s line-level TaxCodeRef. The invoice is still synced; the variance is informational, so you can reconcile the difference in your books.
Error	The push failed. The sync status carries the last error so you can see why before retrying.

A pushed invoice’s QuickBooks DocNumber is shown alongside the status when QuickBooks assigned one different from the Breeze invoice number — this happens when QuickBooks already held a document under Breeze’s number and Breeze retried the push letting QuickBooks assign its own.

Home-currency limitation

QuickBooks invoice push is home-currency only: an invoice can only be pushed when its currency matches the currency your connected QuickBooks company books in (its “home currency”). Foreign-currency invoicing against a QuickBooks realm that uses a different currency, or against a company whose currency Breeze hasn’t captured yet, is not supported — Breeze blocks the push with a clear error rather than mis-booking the invoice at the wrong currency or silently converting it.

You’ll see one of two errors on a blocked push:

• Home currency unavailable: QuickBooks home currency is unavailable, so this invoice cannot be pushed safely. Reconnect QuickBooks to capture it, then retry. — QuickBooks’ home currency was never captured (or the capture failed). Reconnecting QuickBooks re-captures it.
• Currency mismatch: Invoice currency <code> does not match the connected QuickBooks home currency <code>. Cross-currency accounting pushes are not supported., followed by either Enable multi-currency in QuickBooks or invoice in <home currency>. (when your QuickBooks company isn’t confirmed to have multi-currency turned on) or QuickBooks foreign-currency invoice push is not yet supported. (when it does — the seams to support it exist, but the push itself is a later release).

A QuickBooks customer stamped with its own currency (set the first time that customer synced) is checked the same way: if the mapped QuickBooks customer’s currency doesn’t match the invoice’s currency, the push is blocked with a customer-currency mismatch error before anything reaches QuickBooks, even if the realm-level check above would have passed.

Payment pull-back

Once an invoice has been pushed to QuickBooks, payments recorded in QuickBooks against that invoice mirror back into Breeze automatically — the invoice’s balance, status (partially_paid / paid), and payment list update without you doing anything in Breeze. Each mirrored payment carries a QuickBooks badge on the payment row so you can tell it apart from a payment you recorded manually or one collected online through Stripe.

What’s mirrored: a payment (full or partial) entered in QuickBooks against an invoice Breeze pushed there, and a payment deleted in QuickBooks (Breeze removes the matching payment row and recomputes the invoice — a payment you recorded manually on the same invoice is never touched).

What’s not mirrored, on purpose:

• Payments you record in Breeze, or Stripe payments Breeze collects, are not pushed to QuickBooks. That direction — Breeze → QuickBooks payment push — isn’t built yet, which is exactly why the Pull QuickBooks payments switch below exists: with both directions live at once, a payment could double-count (pushed out, then pulled back in as if it were a second, QuickBooks-originated payment).
• Credit memos and QuickBooks-originated refunds don’t flow into Breeze.
• Foreign-currency payments aren’t supported — like invoice push, a payment pull is blocked (and the invoice’s mapping flips to an error you can see) if its currency doesn’t match the invoice’s.
• If QuickBooks records a payment against an invoice you’ve voided in Breeze, Breeze does not apply it — the invoice mapping flips to an error (“Payment pull: Payment received in QuickBooks against a voided invoice”) rather than silently reopening a document you closed. Errors that came from the payment pull are prefixed “Payment pull:” and clear themselves once a payment for that invoice lands cleanly; errors from the invoice push (such as “Deleted in QuickBooks”) are never cleared by a payment.
• If an invoice itself is voided or deleted in QuickBooks, its mapping shows an Error status with the message “Deleted in QuickBooks” in the sync card, and Breeze never recreates it automatically.

How fast it happens: Breeze checks for QuickBooks-side changes every 15 minutes — this scheduled sweep is the guaranteed path and runs the same way in every hosted region. Where available, an Intuit webhook notification triggers an immediate check instead of waiting for the next sweep, but Intuit only supports one webhook URL per app, and Breeze’s hosted deployment uses one Intuit app for both regions — so only the US region receives instant notifications today; the EU region (and any self-hosted deployment without a public webhook URL configured) always mirrors on the 15-minute sweep. Either way, the end state is the same.

Self-hosting and want the faster path? Register POST /api/v1/webhooks/quickbooks as your Intuit app’s webhook endpoint for the Invoice and Payment event groups, and set the app’s verifier token as QBO_WEBHOOK_VERIFIER_TOKEN. Until you do, the endpoint declines every delivery and the sweep does all the work — which is the supported configuration, not a degraded one.

Payment sync is a switch on the connected panel — “Pull payments recorded in QuickBooks back into Breeze invoices.” It is on by default. Turn it off to stop pulling payments from QuickBooks into Breeze — for example, while you’re still reconciling manually and don’t want QuickBooks payments overwriting Breeze’s own record. A Sync now button next to the switch runs a pull immediately rather than waiting for the sweep or a webhook; with Payment sync turned off it declines with “Payment sync is turned off for this connection. Turn on Payment sync to sync now.”

Changing Payment sync or the invoice push mode, and using Sync now, all require the Invoices: write permission and a multi-factor confirmation.

The panel shows the outcome of the last reconcile run underneath. Three messages are worth recognising:

Message	What it means
“run skipped — disabled for this connection”	Payment sync is off. Nothing is wrong; nothing is being pulled either.
“QuickBooks truncated the last change window and the backfill did not complete; payments may be missing”	More changed in QuickBooks than one change window can report. Check recent QuickBooks payments against Breeze by hand.
“N item(s) failed in the last reconcile run”	Some payments could not be applied — open the affected invoices to see why.

Turn it back on and the next sweep resumes from where it stopped — but only within QuickBooks’ 30-day change history. QuickBooks cannot report changes older than that, so if the switch was off (or the connection was disconnected or erroring) for more than a month, payments recorded in the gap are not picked up by the sweep and have to be entered in Breeze by hand. Breeze logs a warning and raises an alert to its operators when it detects that gap, and the connection panel shows the last pull’s outcome.

Customer and item mapping

Before an invoice can push cleanly, Breeze needs to know which QuickBooks customer each of your organizations corresponds to, and which QuickBooks item each of your catalog items corresponds to. The Customer and item mapping panel does this, with Customers and Items tabs.

Click Load mappings and Breeze proposes a match for each record, labelled so you can see how much to trust it:

Label	Meaning
Linked	Already mapped — nothing to do.
Suggested match	One confident match, on an exact email (customers) or SKU (items), or an exact name.
Ambiguous match	More than one plausible candidate. Pick the right one yourself.
No match	Nothing in QuickBooks looks like this record.

Suggestions are proposals only — nothing is written to QuickBooks until you act on a row:

• Confirm match accepts the proposed record, or one you pick from the search box.
• Create new creates a matching customer or item in QuickBooks.
• Unlink breaks an existing mapping.
• Sync now pushes the mapped record’s details to QuickBooks.

Note

Set a default Income account before creating or syncing items — QuickBooks requires one, and Breeze blocks the action rather than creating an unusable item without it.

Mappings feed invoice push directly: a mapped customer is the one the invoice is raised against in QuickBooks. Getting these right before you start pushing invoices avoids duplicate customers in your books.

Importing customers

Once QuickBooks is connected, an Import customers section appears so you can bring your existing QuickBooks customers into Breeze as organizations — no re-typing.

1. In the Import customers section, click Load customers to pull your QuickBooks customer list.
2. Tick the customers you want. Customers you’ve already imported show an Already imported badge, are disabled, and are excluded from select-all.
3. Click Import selected. Breeze reports how many were imported, skipped, and failed, and lists any failures inline so you can see exactly which customer and why.

Note

The import is idempotent — it keys off the QuickBooks customer id, so re-running it never creates duplicates. One QuickBooks company (realm) connects per partner.

Reconnecting and disconnecting

• If the panel shows a Reconnect required badge, Intuit’s authorization has expired — click Reconnect QuickBooks to run the consent flow again. The last error is shown to help you understand why.

• Refresh re-checks the current connection status.

• Disconnect removes the QuickBooks connection from Breeze (MFA-gated).

The Payments sub-tab connects your Stripe account so your customers can pay invoices by card online. This is the one-time, partner-level connection step — the collecting, payment links, and refunds are covered under Online Payments.

Note

You are always the merchant of record and Breeze takes no platform fee. See Online Payments for how the money flows.

Connecting Stripe

Breeze connects to Stripe using a secret API key you paste in from your Stripe dashboard.

1. Open Integrations → Accounting and select the Payments sub-tab.
2. In your Stripe dashboard, copy a secret key — a standard secret key (sk_live… / sk_test…) or a restricted key (rk_live…).
3. Paste it into the key field and click Save key. The field is masked, so the key is never shown back to you.
4. On success the panel switches to the connected view.

Connected view

Once connected, the panel shows:

• The Stripe account it’s linked to, masked to the last few characters (for example acct_••••1A2b).
• The last 4 characters of the saved key.
• A Live or Test mode badge, so you can tell at a glance whether you’re taking real payments.

To disconnect, click Disconnect — this removes the saved Stripe key from Breeze.

What this enables

Connecting Stripe here is what makes online payments possible everywhere else in Breeze:

• Payment links on issued invoices.
• A Pay now button in the Customer Portal.
• Automatic recording of online payments against the invoice, badged Online.

Refunds are reflect-only — you issue them from your own Stripe dashboard and Breeze stays in sync. The full collect-and-refund workflow lives in Online Payments.

---

Related

• Online Payments — collect card payments, send payment links, and handle refunds
• Invoices — issue invoices that push to QuickBooks and carry payment links
• Integrations — the full Integrations page, including PSA, communication, and distributor connections