Excel & Mutero Desktop

Fiscalise spreadsheet invoices with Mutero Desktop — local agent, Excel template, Office.js add-in, invoices, print, and PDF storage. 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. The Excel add-in and bulk upload UI talk to this endpoint; receipts are queued locally and synced to Mutero Cloud after browser sign-in. Keep Mutero running (window or system tray) whenever you use Excel with Mutero.

Download & install

Mutero Desktop for Windows

Automated Windows setup file (`Mutero-Setup.exe`). Automatically registers Excel Trusted Add-in Catalogs and SMB share.

Download and run Mutero-Setup.exe on your Windows PC.
Choose your default Theme Mode (Dark, Light, or System) in the setup wizard.
Launch Mutero Desktop from your Desktop or Start Menu.

1. Sign in with browser

Mutero Desktop opens into the main app shell. If you are not signed in, use Sign in with browser in the sidebar or empty state. This opens Mutero Cloud in your default browser; after sign-in, the app deep-links back and provisions a desktop API key automatically.

No manual API key paste is required. Advanced users can change the Cloud URL under Settings → Advanced.

2. Select one VFD device

Each desktop install supports one active registered VFD. Change the device anytime in Settings. Open a fiscal day before fiscalising.

3. Enable the Excel add-in

Production — almost automatic

The Mutero installer copies the add-in, creates a local network share, and registers an Excel Trusted Add-in Catalog. You only need one click in Excel the first time.

Production (installed Mutero)

Install Mutero. Allow the UAC prompt if Windows asks (registers the Excel catalog share).
Start Mutero, sign in, and open a fiscal day.
In Excel: Insert → Get Add-ins (or Home → Add-ins → More Add-ins).
Open the SHARED FOLDER tab → select Mutero Fiscal → Add.

Files live at %APPDATA%\Mutero\ExcelAddin. Start Menu → Mutero → Enable Excel Add-in opens a short reminder.

Avoid these Excel screens

Do not use Developer → XML → Expansion Packs (wrong feature; certificate errors are expected there). Desktop Excel usually does not show “Upload My Add-in” — that is mainly for Excel on the web. Use SHARED FOLDER instead.

The Excel add-in ribbon includes: Template, Validate, Fiscalise, Open/Close Day, and live Status task pane.

Ribbon: Template, Validate, Fiscalise, Open/Close Day, Status (task pane).

Add-in manifesttext

desktop/excel-addin/manifest.xml

4. Excel template & bulk upload

Use Mutero_Fiscal_Invoice.xlsx (or Insert Invoice Template from the task pane) with columns: invoice_number, date, customer_name, customer_tin, item_description, quantity, unit_price, tax_code, hs_code, currency, notes.

For credit notes, use Mutero_Fiscal_Credit_Note.xlsx (or Insert Credit Note Template). Fill in:

Easiest option: Mutero web app

If the Excel template feels heavy, open the fiscalised invoice in the Mutero web app, then click Issue Credit Note.

Credit Note No. (for example XL-CN-001)
Original Invoice No. (or the FRN of a fiscalised invoice)
Reason (required)

Leave line items blank to credit the full original, or list matching lines for a partial credit. The original must already be fiscalised in Mutero.

tax_code	ZIMRA	Notes
15%	Tax ID 1	Standard VAT
0%	Tax ID 2	Zero-rated — requires 8-digit HS code
exempt	Tax ID 3	Exempt (no taxPercent on ZIMRA payload)

Tax codes & FDMS preflight

Empty tax_code on the Mutero Excel template defaults to 15% (template contract). Known labels (15%, 0%, exempt, VAT, etc.) resolve automatically. Any other unrecognized non-empty tax value is blocked — it never silently becomes 15%. Zero-rated / exempt lines need an 8-digit HS code. If customer_tin is set, Mutero sends ZIMRA buyerData (name + TIN).

Currency: Excel dropdown USD / ZiG. In Mutero Cloud, set currency on New/Edit Invoice. Zoho Books uses native currency_code (not a Mutero custom field).

Payment method is not collected in the Cloud invoice UI or Excel template. ZIMRA requires a payment line; Mutero defaults to Cash. APIs may pass payment_method or payment_methods to override.

Desktop → Upload also accepts the same workbook. Invoices queue locally with source: excel and idempotent external_id.

Desktop hub features

Invoices — fiscal receipts from cloud (FRN, status, source); ZIMRA verify; print local PDFs.
Fiscal day — open/close day, device status, recent day history.
Queue — local SQLite buffer plus cloud fiscalization queue (excel, desktop, api, zoho_books).
PDF storage — default Documents/Mutero/Fiscal PDFs/{business_id}/ or a custom folder in Settings.
Offline — connectivity badge; local queue holds invoices until cloud is reachable.
System tray — closing hides to tray so port 18989 keeps running for Excel. Use Quit from the tray to exit fully.

Local agent API

Example — fiscalise from scripthttp

POST http://127.0.0.1:18989/fiscalize
Content-Type: application/json

{
  "source": "desktop",
  "external_id": "INV-1001",
  "invoice_number": "INV-1001",
  "currency": "USD",
  "payment_method": "Cash",
  "items": [{ "description": "Item", "quantity": 1, "unit_price": 10, "total": 10, "tax_percent": 15, "tax_id": 1 }]
}