MuteroDocs

Xero Accounting Integration Guide

Connect your Xero organisation in the Mutero Integrations Hub, map tax rates for ZIMRA, auto-fiscalize AUTHORISED sales invoices and allocated credit notes, and get FRN verification links written back to Xero history.

Invoice numbering stubs
Mutero prefixes Xero documents for idempotency: invoices become XR-{InvoiceNumber} (e.g. XR-INV-0100), and credit notes become XR-CN-{CreditNoteNumber}.
Cloud integration (not Desktop credentials)
Xero is a Mutero Cloud connector. You connect in the web Integrations Hub — there is no Desktop URL/API-key form. Mutero Desktop only shows whether Xero is active on your account. Contrast with Odoo / QuickBooks Desktop / Pastel, which store credentials on the local agent.

1. Overview

Connect your Xero organisation from the Mutero Integrations Hub (one-click OAuth). After connect:

  • AUTHORISED / PAID ACCREC invoices sync and auto-fiscalize (when enabled).
  • ACCRECCREDIT credit notes fiscalize only when allocated to an already-fiscalized Mutero original (ZIMRA RCPT015 / RCPT032).
  • After ZIMRA confirm, Mutero posts a history note on the Xero invoice or credit note with the FRN and verification URL.
  • Use Sync Now from the Dashboard Integrations Hub to pull recent invoices and credit notes anytime.
  • Mutero Desktop lists active cloud integrations (including Xero) on Home for status — connection and settings stay in the web app.

2. Connect Xero

What you need
A Xero login with permission to authorise apps (Advisor or Standard), and access to the correct organisation. You do not create a Xero Developer app or paste Client IDs — Mutero handles that.
  1. Open Integrations Hub.
  2. Find Xero Accounting and click Connect Xero.
  3. On the Xero consent screen, select your organisation and authorize Mutero.
  4. You return to Mutero with the organisation linked. Mutero immediately checks Xero tax rates — if a ~15% sales rate is missing or unmapped, the Hub shows Setup incomplete and Sync stays blocked until you fix it (see Tax rates). Then open Configure for auto-fiscalize and default VFD.

3. Invoice & credit note numbering

DocumentMutero invoice numberMatched by
InvoiceXR-INV-0100Xero Invoice ID
Credit noteXR-CN-0001Xero Credit Note ID

Mutero matches documents by Xero's document ID so Sync Now and real-time updates cannot double-fiscalize the same invoice or credit note.

4. Tax rates in Xero & Mutero mapping

Important — do this before Sync
Xero's locked defaults are often all 0% (including "Tax on Sales"). That does not satisfy ZIMRA 15% VAT. Create a new 15% sales rate (e.g. VAT on Sales), map it to ZIMRA Standard in Tax Mapping → Xero, then Recheck tax. Until that passes, the Hub shows Setup incomplete and Sync is blocked. See also the cross-integration table in Integrations → Tax rates by integration.

Tax Mapping translates each Xero tax name on an invoice line into a ZIMRA tax ID. Without a match, Mutero blocks the document — it never invents 15% VAT.

  1. In Xero, open Settings → Tax rates. Locked defaults are often all 0% (Tax on Sales, Tax Exempt, Tax on Purchases, Sales Tax on Imports) — that is not enough for ZIMRA 15% VAT.
  2. Click + New Tax Rate and create a sales rate at 15% (recommended name: VAT on Sales). Optionally add Zero Rated at 0%. You can keep Tax Exempt for exempt sales.
  3. After you connect Xero, Mutero seeds common names automatically. Open Tax Mapping → Xero and map the exact 15% rate Name (or TaxType) to ZIMRA Standard. Map Tax Exempt / Zero Rated to Exempt / Zero Rated as needed. Set an 8-digit Default HS Code on zero-rated / exempt rows (RCPT047 / RCPT048).
  4. In the Hub, open Configure → Recheck tax until status is ready (Sync unlocks). Then authorise a test invoice in Xero → Sync Now → check Sync Logs.
Xero rate (typical)What to doMutero / ZIMRA
Tax on Sales (locked, often 0%)Do not use as 15% VAT. Create a new 15% sales rate instead.Fails setup check if only 0% sales rates exist
VAT on Sales / 15% (you create)New tax rate at 15%, apply to sales/revenue linesMap Name → 1 — Standard
Zero Rated / 0% (optional)Create if you sell zero-rated goodsMap → 2 — Zero Rated + HS code
Tax Exempt (locked, 0%)OK for exempt sales lines if you use this nameMap → 3 — Exempt + HS code
Tax on Purchases / ImportsIgnore for Mutero sales fiscalisationNot used for ACCREC sync
Xero TaxType / name (seeded examples)RateZIMRA Tax ID
OUTPUT2, VAT on Sales, 15%, VAT 15%15%1 — Standard
ZERORATEDOUTPUT, Zero Rated, 0%0%2 — Zero Rated
EXEMPTOUTPUT, Tax Exempt, Exempt, No VAT0%3 — Exempt
Unknown tax codes never default to 15%
Unmapped Xero tax types are blocked before ZIMRA submit. When the Xero contact has a tax number, Mutero sends buyer TIN data to ZIMRA. Currency must be USD or ZiG.
Transaction preferences
Prefer tax exclusive line amounts unless your catalog is tax-inclusive. Apply the correct tax type on every sales line. Discounts should not invent a separate unmapped tax code.

5. How to issue a credit note

What is a credit note?

A credit note is the opposite of an invoice: it reduces what a customer owes (or refunds money already paid). In fiscalisation terms, ZIMRA already recorded the original sale; the credit note tells ZIMRA that part (or all) of that sale is reversed. Mutero links it to the original fiscal receipt so ZIMRA accepts it.

Example: you invoiced $322 for a service, fiscalised it, then the customer cancels. You issue a $322 credit note against that invoice. In Xero the invoice balance goes to zero; in Mutero/ZIMRA a credit fiscal document is issued against the original FRN.

Create the credit note in Xero (or use Mutero's Issue Credit Note). Do this only after the original invoice already shows an FRN in Mutero.

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

What to fill on Xero's “New credit note” screen

Xero has no field labelled “Reason”. Use Reference for that (optional for Mutero — we invent one if blank).

  • Contact — same customer as the original invoice.
  • Issue date — today is fine.
  • Credit note number — leave Xero's auto number (e.g. CN-0006).
  • Reference — short why (e.g. “Returned goods”, “Billing error”). Optional; Mutero will use Xero credit note CN-… if empty.
  • Currency — USD or ZiG only (same as the fiscalised invoice).
  • Tax — match the original (usually Tax exclusive + Tax on Sales).
  • Line items — what you are crediting (qty/price/account/tax). Partial credits are fine.
  • Less Credit to INV-… at the bottom — must show the credit applied to the fiscalised invoice. Remaining credit should be $0 if you are fully reversing it.

Fastest way in Xero

Create the credit note from the invoice itself so Xero applies it automatically.

  1. In Xero, open Sales → Invoices.
  2. Open the invoice you want to credit (usually under Awaiting payment).
  3. Click the ⋯ menu (top right), then choose Create and apply credit.
  4. Xero opens a New credit note pre-filled from that invoice. Edit quantities or remove lines if you only need a partial credit.
  5. Optionally put a short why in Reference (there is no separate Reason field).
  6. Click Approve (not Save as draft). Xero applies the credit to the invoice — you should see something like Less Credit to INV-….
  7. In Mutero → Integrations Hub → Xero, click Sync Now. Approving in Xero does not by itself update Mutero unless a Xero webhook delivers the event.

Same steps as Xero’s guide: Add a credit note to a customer's invoice ↗.

Alternative: new credit note, then allocate

  1. Go to Sales → Sales overview (or Invoices).
  2. Click the arrow next to New and choose Credit note.
  3. Enter the contact, lines, tax, and optionally a why in Reference.
  4. Click Approve, then allocate the credit to the fiscalised invoice when Xero asks (or allocate later from the credit note).
  5. In Mutero, click Sync Now for Xero.
What happens next
After Sync Now (or a working Automated Sync webhook), Mutero fiscalises the approved, allocated credit note and writes the FRN back to Xero history. Check Sync Logs if nothing appears under Fiscal Documents.
If Sync Logs shows an error
Usually the original invoice is not fiscalised yet in Mutero, the credit note is still a draft, or it is not allocated to that invoice. Fix that in Xero, then Sync Now again. An empty Reference field is fine.

6. Enable auto-fiscalize (real-time)

What this enables
When Auto Fiscalize is on, AUTHORISED / PAID sales invoices (and allocated credit notes) are pulled into Mutero as they change in Xero, fiscalized with ZIMRA, written back to Xero History & Notes, and reflected in Sync Logs and notifications. Sync Now remains available as a manual fallback.

Checklist in Mutero

  1. Open Integrations Hub and confirm Xero is Connected.
  2. Click Configure → turn Automated Sync & Fiscalize ON.
  3. Set a default VFD device on the integration (required so receipts can be queued without Sync Now).
  4. Complete Tax Mapping for Xero.
  5. Open a fiscal day on that VFD before go-live.

What gets fiscalized

  • Invoices — sales invoices in AUTHORISED or PAID status. Drafts, voided, and deleted are skipped.
  • Credit notes — receivable notes allocated to an already-fiscalized XR-… original. Mutero blocks a second credit when the original is already fully credited.
  • Numbers use XR- / XR-CN- stubs (e.g. Xero CN-0005 → XR-CN-0005); Sync Logs show progress from queued to success.

Credit note webhooks (separate from invoices)

Mutero's handler already supports CREDITNOTE events. In the Xero Developer Portal, open your app → Webhooks and ensure you subscribe to Credit notes in addition to Invoices. Invoice-only subscriptions explain why invoices auto-fiscalize but credit notes need Sync Now.

Verify it works

  1. In Xero, authorize (or update) a test sales invoice that is not Draft.
  2. Within about a minute, open Mutero → Sync Logs (filter platform = Xero) for a new row.
  3. Confirm a Mutero notification and, after ZIMRA confirm, a History & Notes entry on the Xero invoice with FRN + verification URL.
  4. If nothing arrives: confirm Auto Fiscalize is on, a default VFD is set, a fiscal day is open, and tax mapping is complete — then try Sync Now.

7. Writeback

After successful ZIMRA submission, Mutero appends a History & Notes entry on the Xero invoice or credit note containing:

  • ZIMRA fiscal receipt number (FRN)
  • Device ID
  • Verification URL

Writeback failures are non-blocking — fiscalization still succeeds.

8. Sync Now & sync logs

Use Sync Now on the Integrations Hub to pull recent AUTHORISED invoices then credit notes. Track outcomes under Sync Logs (filter platform = Xero). Mutero Desktop Home shows when Xero is active on your account but does not run Sync Now.

9. Troubleshooting

  • Token expired / re-authorize needed — click Re-authorize Xero under Configure in the Integrations Hub.
  • Unlinked credit note — allocate the credit note to the original invoice in Xero, ensure the original is fiscalized, then Sync Now.
  • Invoices auto-fiscalize but credit notes do not — in the Xero Developer Portal, add a Credit notes webhook subscription (Invoices alone is not enough). Or use Sync Now.
  • Already fully credited — Mutero refuses another credit note when remaining balance is 0. Open the original invoice to see linked credit notes / FRNs.
  • Fiscal day closed — open the fiscal day on the default VFD (Dashboard or Desktop) before Sync Now.
  • Missing default device — set a default VFD on the Xero integration (Configure) so auto-fiscalize can queue receipts.
  • 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.
  • Unmapped tax blocked — map the Xero tax type under Tax Mapping.
← Integrations overviewOpen Integrations Hub →