QuickBooks Online Integration Guide
Connect QuickBooks Online in the Mutero Integrations Hub — sync invoices and credit memos, map ZIMRA tax rates, and write FRN verification links back to PrivateNote.
Cloud integration — managed in the web app
QuickBooks Online is a Mutero Cloud connector (like Zoho Books and Xero). Connect, disconnect, Sync Now, and auto-fiscalize live in the Integrations Hub. Mutero Desktop only shows whether QBO is active on your account — it does not store Intuit credentials. This is separate from QuickBooks Desktop (local QBWC on Windows).
Invoice numbering stubs
Mutero prefixes QuickBooks Online documents: invoices become
QBO-{DocNumber}, credit memos become QBO-CN-{DocNumber}. Desktop QBD uses QB- — do not mix them.1. Overview
Connect your QuickBooks Online company from the Mutero Integrations Hub (one-click OAuth). After connect:
- Recent invoices sync and auto-fiscalize (when enabled).
- Credit memos fiscalize when linked to an already-fiscalized Mutero original (ZIMRA RCPT015).
- After ZIMRA confirm, Mutero appends the FRN and verification URL to the QBO PrivateNote.
- Use Sync Now from the Integrations Hub anytime. With Auto Fiscalize on, invoice changes sync in near real time.
2. Connect QuickBooks Online
What you need
An Intuit login that can authorize apps for your QuickBooks Online company. You do not create an Intuit Developer app or paste Client IDs — Mutero handles that.
- Open the Integrations Hub.
- Find QuickBooks Online and click Connect QuickBooks Online.
- Authorize Mutero and select your company on the Intuit consent screen.
- You return to Mutero with the company linked. Use Configure for auto-fiscalize and a default VFD.
3. Tax rates in QuickBooks Online & mapping
Tax Mapping translates each QBO tax code name into a ZIMRA tax ID. Without a match, Mutero blocks the document — it never invents 15% VAT.
- In QBO, open Taxes (or Settings → Sales tax) and ensure sales tax codes match ZIMRA.
- After you connect, Mutero seeds common labels. Open Tax Mapping → QuickBooks Online and confirm the rows (add any custom TaxCode names yourself).
- On zero-rated / exempt mappings, set an 8-digit Default HS Code.
- Verify: create a test invoice in QBO → Sync Now → check Sync Logs. Success means tax resolved; a tax-mapping error means add that TaxCode name under QBO.
| QBO TaxCode / name (examples) | ZIMRA Tax ID |
|---|---|
| TAX, TAXABLE, Taxable, VAT, 15%, Standard | 1 — Standard 15% |
| Zero Rated, 0% | 2 — Zero Rated |
| NON, NONTAXABLE, Non, Exempt, Out of Scope | 3 — Exempt |
4. How to issue a credit memo
Create the credit memo in QuickBooks Online. Mutero will sync and fiscalise it. The original invoice must already be fiscalised in Mutero first.
Easiest option: Mutero web app
If QuickBooks feels confusing, open the fiscalised invoice in the Mutero web app, then click Issue Credit Note. That handles the ZIMRA credit note for you. Use the QBO steps below only when you also want the credit memo in QuickBooks.
Steps in QuickBooks Online
- Open + New → Credit memo (or open the original invoice and create a credit from there).
- Choose the same customer and link the credit memo to the original invoice.
- Put a short reason in the Memo / Private note field (for example: “Returned goods”).
- Save the credit memo.
What happens next
With Automated Sync on, Mutero fiscalises the credit memo and adds the FRN to PrivateNote. You can also click Sync Now.
5. Enable auto-fiscalize (real-time)
What this enables
When Auto Fiscalize is on, invoice and credit memo changes in QuickBooks Online sync into Mutero, fiscalize with ZIMRA, append FRN/QR to PrivateNote, and update Sync Logs and notifications. Sync Now remains the manual fallback.
Checklist in Mutero
- Open Integrations Hub and confirm QuickBooks Online is Connected.
- Click Configure → turn Automated Sync & Fiscalize ON.
- Ensure a default VFD is selected and a fiscal day is open.
- Complete Tax Mapping for QuickBooks Online.
What gets fiscalized
- Sales invoices use
QBO-; credit memos useQBO-CN-and require a linked fiscalized original. - Voided or unmapped-tax documents are skipped or blocked in Sync Logs — never invent 15%.
Verify it works
- In QuickBooks Online, create or update a sales invoice (not voided).
- Open Mutero → Sync Logs (filter = QuickBooks Online) for a new queued / success row.
- Confirm a Mutero notification and, after ZIMRA confirm, a PrivateNote on the QBO document with FRN + verification URL.
- If nothing arrives: confirm Auto Fiscalize, default VFD, fiscal day, and tax mapping — then use Sync Now to prove the connection independently.
6. Writeback
After successful ZIMRA submission, Mutero appends a PrivateNote on the QBO invoice or credit memo containing the FRN, device id, and verification URL. Failures are non-blocking.
7. Troubleshooting
- Token expired — use Re-authorize QuickBooks under Configure.
- Unmapped tax — map the TaxCode name under Tax Mapping.
- Credit memo skipped — fiscalize the linked invoice first, then Sync Now.
- Nothing fiscalized after an invoice change — turn Auto Fiscalize on, set default VFD, open fiscal day, finish Tax Mapping, then check Sync Logs or run Sync Now.