MuteroDocs

Odoo Cloud Integration Guide

Connect Odoo Online or Odoo.sh from the Mutero Integrations Hub. Required Zimbabwe tax/currency settings, credentials (URL, database, username, API key), Mutero tax mapping, Sync for posted invoices, and FRN chatter writeback.

Invoice numbering stubs
Mutero prefixes Odoo Cloud documents for idempotency: invoices become ODC-{InvoiceNumber}, and credit notes become ODC-CN-{CreditNoteNumber}. Desktop Odoo uses OD- — do not run both connectors against the same database.
Cloud integration (not Desktop)
Odoo Cloud is a Mutero Cloud connector. You enter credentials in the web Integrations Hub. For self-hosted Odoo that is only reachable on a LAN, use Odoo & Mutero Desktop instead.
Odoo plan must allow External API
Odoo only exposes the External API on plans that include it (typically Custom / higher tiers — not One App Free or Standard). If connect fails with access / authentication errors after a correct API key, check your Odoo subscription or ask Odoo support whether External API is enabled for the database.
No native webhooks
Odoo does not provide invoice webhooks that Mutero can subscribe to for fiscalisation. Use Sync Now or the Integrations Hub 3-minute poller. Only posted customer invoices and refunds are synced.
DIY setup checklist
If you are connecting this yourself, complete the steps in this guide (credentials → tax → Sync) before going live. Mutero blocks Sync when tax setup is incomplete. Prefer assisted setup? Request it for a once-off $50 from the Integrations Hub.
Required Odoo settings (quick)
Fiscal Country Zimbabwe · Default Sales Tax ~15% (Sales scope) — not Exempt · create Zero Rated + Exempt for special lines · map taxes in Mutero · Sync posted invoices only. Details in §4 Required Odoo settings.

1. Overview

Mutero talks to Odoo over JSON-RPC (/jsonrpc). After you connect:

  • Posted customer invoices sync and auto-fiscalize (when enabled). Drafts are skipped.
  • Credit notes fiscalize only when reversed from an already-fiscalized Mutero original (ZIMRA RCPT015 / RCPT032).
  • After ZIMRA confirm, Mutero posts FRN + verification URL to the invoice chatter.

2. Collect the four fields (exact steps)

You need four values for Mutero. Use the same Odoo user that can open Accounting → Customers → Invoices (admin is fine for setup).

2.1 Odoo URL

  1. Sign in to your Odoo Online database in the browser.
  2. Copy the origin from the address bar — scheme + host only, no path after the domain.

Example: if you are on https://orbit-revolution.odoo.com/odoo/settings, the URL is https://orbit-revolution.odoo.com

Do not add a trailing slash. Custom domains on Odoo.sh work the same way.

2.2 Database name

For Odoo Online (*.odoo.com), the database name is almost always the subdomain (the part before .odoo.com).

Example: URL https://orbit-revolution.odoo.com → database orbit-revolution

If you have multiple databases, the login / database selector screen shows the exact database name — use that string verbatim (case-sensitive).

2.3 Username

The login email of the Odoo user (the email you type on the Odoo login page), not the company display name.

Confirm it under Settings → Users & Companies → Users → open the user → Email / Login field.

2.4 API key or password

Mutero accepts either an API key or the user’s local password. Both are sent in the same External API auth slot. Prefer an API key when you can create one.

Yes — password works
If you cannot find Generate Key, you can paste a local user password into Mutero’s “API Key or Password” field instead. On Odoo Online you often have no local password yet (you sign in via Odoo’s auth). Set one first: Settings → Users & Companies → Users → open your user → Action → Change Password → set New Password → use that password in Mutero.

If you see Generate / New API Key

Path A — Settings

  1. Open Settings → General Settings.
  2. Search api (optional), then under Permissions click → Manage API Keys.
  3. Create a key (description e.g. Mutero VFD). On newer Odoo versions choose Persistent Key if asked.
  4. Click Generate Key, copy it immediately, paste into Mutero.

Path B — My Profile (most reliable)

  1. Click your avatar / initials (top right) → My Profile / Preferences.
  2. Open Account Security (or Security).
  3. Click New API Key / Add API Key → Generate → copy.
If Generate Key is missing
Common causes:
  • You opened the Settings description of API Keys but not the actual key list — use → Manage API Keys, or Path B (My Profile).
  • Your Odoo plan may not include External API (often Custom only — not One App Free / Standard). Password auth can still be tried; if both fail, upgrade/check the plan.
  • Use the password path above (Change Password → paste password in Mutero).

Filled example (Orbit Revolution trial)

  • URL: https://orbit-revolution.odoo.com
  • Database: orbit-revolution
  • Username: your@login.email
  • API key or local password: (paste one of them)

3. Connect in Mutero

  1. Open Integrations Hub.
  2. Find Odoo Cloud and click Connect.
  3. Paste URL, database, username, and API key or password → save. Mutero authenticates via JSON-RPC before storing credentials.
  4. Mutero seeds default tax mappings and checks sale taxes. If a ~15% sales rate is missing or unmapped, the Hub shows Setup incomplete and Sync stays blocked until you fix it (see Tax Mapping).

Mutero does not need any Odoo developer env var on the server — unlike Sage Accounting ZA.

4. Required Odoo settings

Configure these in Odoo before (or right after) connecting Mutero. Path: Invoicing / Accounting → Configuration → Settings (or Configuration → Taxes for the tax list).

4.1 Fiscal country

  • Set Fiscal Country to Zimbabwe.
  • Do not leave a US/EU chart as the living default while fiscalising ZIMRA invoices — leftover labels like 15% (US) / Exempt (US) often break tax pickers and confuse Mutero mapping.

4.2 Taxes (Sales scope)

Open Configuration → Taxes and create active taxes with Tax Scope = Sales (not Purchase-only):

Name (example)AmountUse
15%15%Default for standard-rated sales (ZIMRA Standard)
Zero Rated0%Zero-rated lines only
Exempt0% / exemptExempt lines only — never the company default
  • Default Sales Tax = your 15% sales tax (not Exempt).
  • Default Purchase Tax can stay 15% purchase if you use vendor bills; Mutero only fiscalises customer invoices / refunds.
  • If the invoice tax dropdown shows No record found with a Sale filter, you do not have active Sales-scoped taxes yet — create them under Configuration → Taxes. Settings can still show a stale default (e.g. Exempt (US)) even when the Sale search is empty.

4.3 Tax included vs excluded prices

  • Odoo Tax Included is supported. Mutero converts lines to tax-exclusive amounts for ZIMRA (e.g. price 4,000 with 15% included → exclusive 3,478.26 + tax 521.74 = 4,000).
  • Tax Excluded also works — keep unit price exclusive and let Odoo add 15%.
  • Prefer one company-wide choice and stick to it so invoice math stays consistent.

4.4 Currency

  • Mutero fiscalises USD and ZiG only. Set company Main Currency to the currency you invoice in most often.
  • To put a different currency on one invoice without changing the company main currency: enable Multi-Currencies under Invoicing Settings → Currencies, then activate USD / ZiG under Configuration → Currencies. Draft invoices then show an editable currency field.
  • Automatic ECB rates are optional; set manual rates if Odoo cannot quote ZiG/USD the way you need.

4.5 HS codes

  • HS codes are not configured on the company tax defaults screen.
  • In Odoo they usually live on the product (Intrastat / customs fields when that app is installed), or you can skip them in Odoo.
  • For ZIMRA, set a default HS per tax (or product) in Mutero Tax Mapping → Odoo Cloud.

4.6 Before Sync — invoice checklist

  • Customer invoice is Posted (not Draft).
  • At least one product / service line with quantity and price > 0.
  • Line tax is a Sales tax mapped in Mutero (15% → ZIMRA Standard).
  • Currency is USD or ZiG.

5. Tax Mapping in Mutero

After Odoo has Sales taxes, map them in Mutero so Sync is not blocked:

Tax Mapping → Odoo Cloud
  • Map by tax name or amount string (e.g. 15%) → ZIMRA Standard (tax ID 1).
  • Map Zero Rated and Exempt to the matching ZIMRA tax IDs.
  • Optional: set a default HS code on each mapping.
  • Use Configure → Recheck tax on the Odoo Cloud card after Odoo tax changes.
Mutero blocks Sync without a ~15% map
If setup_health.tax_ok is false, the Hub shows Setup incomplete until a ~15% sales rate is mapped to ZIMRA Standard.

6. Sync & Fiscalize

  1. In Odoo, create a customer invoice and Confirm / Post it (drafts are ignored).
  2. In Mutero, ensure Automated Sync & Fiscalize is on (Configure).
  3. Click Sync Now, or wait for the ~3-minute poller.
  4. Invoices are claimed with the ODC- prefix and queued for ZIMRA. After confirm, Mutero posts FRN + verification URL to Odoo chatter.
Source updates & deletes
Each Sync reconciles against Odoo:
  • Update: if the posted invoice still exists and Mutero has not fiscalized it yet, Mutero refreshes customer, lines, totals, and the pending receipt from Odoo.
  • Delete: if the move is no longer a posted customer invoice in Odoo (reset to draft, cancelled, or deleted), Mutero removes the unfiscalized Mutero invoice, its pending queue/receipt, and non-success sync logs.
  • Fiscalized invoices are never updated or deleted from Sync — ZIMRA history stays intact.
If Sync Logs show two rows for one invoice
Prefer Retry Queue / Cancel on the Odoo Cloud row — do not Fiscalise the same document from both a “Mutero Invoices” twin and the Odoo row. Mutero merges integration rows by external id after the latest deploy.

7. Credit Notes

ZIMRA requires every credit note to reference a previously fiscalized original (RCPT015 / RCPT032).

  • Easiest: open the fiscalised invoice in Mutero → Issue Credit Note.
  • In Odoo: open the fiscalised customer invoice → Credit Note / Reverse → post the refund → Sync Now in Mutero (ODC-CN-…).
Unlinked refunds fail
If the Odoo refund has no reversed_entry_id pointing at a fiscalized Mutero invoice, sync will fail until the original is fiscalized and the link is present.

8. Operations & troubleshooting

  • Rotate keys in Odoo (Manage API Keys), then update Configure in Mutero if Sync fails with authentication errors.
  • The database must be reachable from Mutero Cloud over HTTPS (Odoo Online / Odoo.sh).
  • Disconnect removes the Mutero integration document. Re-enter credentials to reconnect.
  • Empty tax dropdown (Sale filter): create active Sales-scoped taxes under Configuration → Taxes; reset Default Sales Tax to 15%.
  • RCPT022 / line price: usually a tax-included line that failed on an older Mutero build — update Mutero, then Retry Queue once (do not double-fiscalise).
  • “No line items”: Odoo 18 product lines are supported on current Mutero; re-Sync after deploy if you hit this on an older build.