MuteroDocs

QuickBooks Desktop

Fiscalise QuickBooks Desktop invoices and credit memos with Mutero Desktop — local agent, QuickBooks Web Connector (qbXML), offline queue, and QB- / QB-CN- numbering. This page is a living doc updated as features ship.

Local agent on localhost:18989
Mutero Desktop runs a local HTTP agent at http://127.0.0.1:18989. Intuit's QuickBooks Web Connector (QBWC) talks to /qbwc on that agent; receipts are queued locally and synced to Mutero Cloud after browser sign-in. Keep Mutero running (window or system tray) whenever you use QuickBooks Desktop with Mutero.
Desktop-only environment (not QuickBooks Online)
This connector is for QuickBooks Desktop on Windows (Pro / Premier / Enterprise) via the QuickBooks Web Connector. It is not QuickBooks Online. Company file, QBWC, and Mutero Desktop must run on the same PC — the SOAP endpoint binds to 127.0.0.1 only.

Download & install

Mutero Desktop for Windows

Automated Windows setup file (`Mutero-Setup.exe`). No technical setup or terminal commands required.

  1. Download and launch Mutero-Setup.exe on the same Windows PC where QuickBooks Desktop runs.
  2. Select your preferred theme (Dark, Light, or System) in the setup wizard.
  3. Launch Mutero Desktop from your Desktop or Start Menu.

1. Sign in with browser

Open Mutero Desktop and use Sign in with browser. This opens Mutero Cloud; after sign-in the app deep-links back and provisions a desktop API key automatically. QuickBooks never signs into Mutero Cloud directly.

2. Select one VFD device

Each desktop install supports one active registered VFD. Open a fiscal day before fiscalising.

3. Enable QuickBooks Desktop in Mutero

Credentials & files — where they come from

ItemWhere to get it
QBWC usernameDefaults to mutero (shown in Desktop Settings). Enter the same value in QuickBooks Web Connector.
QBWC passwordGenerated once when you click Enable connector (or Regenerate password) in Mutero Desktop → Settings → QuickBooks Desktop. Copy it immediately — paste into QBWC when it prompts. Not stored in Mutero Cloud.
.qwc application fileDownload from Mutero Desktop (Mutero_QuickBooks_Desktop.qwc). Points QBWC at http://127.0.0.1:18989/qbwc.
QuickBooks Web ConnectorInstall from Intuit if missing (bundled with many QBD editions, or download from Intuit's QBWC page). Open it from the Windows Start menu while the company file is open in QuickBooks Desktop.
  1. In Mutero Desktop → Settings → QuickBooks Desktop, click Enable connector.
  2. Copy the one-time QBWC password (username defaults to mutero).
  3. Click Download .qwc and save Mutero_QuickBooks_Desktop.qwc.
  4. Open QuickBooks Web Connector → Add an application → select the .qwc file → paste the password when prompted → allow access when QuickBooks asks.
  5. Keep QuickBooks Desktop (company file open) and Mutero running. QBWC polls every few minutes and exchanges qbXML with http://127.0.0.1:18989/qbwc.
Same PC only
QBWC and Mutero Desktop must run on the machine where QuickBooks Desktop is installed. The SOAP endpoint binds to 127.0.0.1 and is not exposed to the network.

4. Invoice numbering (QB- stub)

Mutero prefixes QuickBooks RefNumber values with QB- (parallel to Zoho ZB- and Excel XL-). Prefixing is idempotent.

QBD DocNumberMutero invoice / external_id
1001QB-1001
INV-2026-5QB-INV-2026-5
CM-12 (credit memo)QB-CN-CM-12

5. How to issue a credit memo

Easiest option: Mutero web app
If QuickBooks Desktop 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 QBD steps below only when you also want the credit memo in QuickBooks.

Create the credit memo in QuickBooks Desktop. Mutero Desktop will pick it up. The original invoice must already be fiscalised in Mutero.

Steps in QuickBooks Desktop

  1. Create a Credit Memo for the same customer.
  2. Link it to the original invoice (LinkedTxn), or put Original: 1001 in the memo (use the real invoice number).
  3. Put a short reason in the Memo field.
  4. Save it, then let Web Connector / Mutero Desktop sync.

6. Safety gates (avoid ZIMRA rejects)

Before anything reaches ZIMRA, Mutero Desktop validates each QB document. Failures land in the local Queue with a clear status instead of submitting a bad fiscal payload.

  • BLOCKED — unmapped tax code, missing 8-digit HS on zero-rated/exempt, unsupported currency, or totals mismatch. Fix in QB or Tax Mapping, then re-sync.
  • NEEDS_REVIEW — Auto-fiscalise is off; open Queue and click Approve.
  • WAITING_ORIGINAL — credit memo waiting until the linked QB-… invoice is confirmed (does not burn retries).
  • BLOCKED_FISCAL_DAY — fiscal day closed; opens when you reopen the day.
Unknown tax codes never default to 15%
Map QuickBooks tax names under Dashboard → VFD → Settings → Tax mapping (platform: QuickBooks Desktop), then in Mutero Desktop click Sync tax mappings from cloud. When the QB customer has a Tax ID / TIN, Mutero sends ZIMRA buyerData (name + TIN, RCPT043).

7. Tax rates in QuickBooks & mapping

In QuickBooks Desktop, set up sales tax codes / items that match ZIMRA (Lists → Item List or Sales Tax Code List, depending on your edition). Recommended labels:

QB tax label (examples)ZIMRA Tax ID
Tax, Taxable, VAT, Standard, 15%1 — Standard 15%
Zero Rated, 0%2 — Zero Rated
Non, Non-Taxable, Exempt, Out of Scope3 — Exempt

Known labels resolve automatically. Everything else must be mapped under Dashboard → VFD → Settings → Tax mapping (platform: QuickBooks Desktop), then in Mutero Desktop click Sync tax mappings from cloud. Zero-rated / exempt lines need an 8-digit HS code from a QB custom field (name containing HS), the tax mapping's default HS, or Desktop's Default HS code setting.

Currency must be USD or ZiG (including common QB FullName forms). Other currencies are blocked.

8. Writeback

After a successful fiscalisation, Mutero queues a qbXML Memo update on the next QBWC session, appending the Mutero FRN and verification URL. If QuickBooks reports a stale EditSequence, Mutero re-queries the txn and retries. Failures are non-blocking and logged.

Troubleshooting

  • QBWC authenticate fails — Mutero shows a sticky error in Settings and a desktop notification. Regenerate the password and update Web Connector.
  • Queue status BLOCKED — read the error column (tax / HS / currency / totals). Do not force-approve blocked items.
  • Credit memo WAITING_ORIGINAL — fiscalise the original invoice first; ensure LinkedTxn or Memo references the DocNumber.
  • Already fiscalised but QB changed — Mutero will not re-submit; issue a credit note instead.
  • Check Mutero Desktop → Queue and Activity logs for enqueue / ZIMRA errors.