Zoho Books ZIMRA Fiscalisation — Integration Guide

Create the Buyer TIN and VAT Custom Fields

Zoho Books has no TIN or VAT field for Zimbabwe, so you must add them once. Go to Settings → Preferences → Invoices → Field Customization → + New Custom Field and create two text fields on the Invoice module:

Zoho derives the API name from the label, so a label of "Buyer TIN" gives you cf_buyer_tin. That is fine — we accept any of cf_tin, cf_buyer_tin, cf_customer_tin, cf_tin_number or cf_tax_id for the TIN, and cf_vat, cf_buyer_vat, cf_vat_number, cf_vat_no or cf_customer_vat for the VAT number. Check the exact API name Zoho generated under Field Customization before you go live.

Add the Line-Item Custom Fields (Optional)

Under Settings → Preferences → Items → Field Customization (line-item level) add cf_hs_code for the HS code and cf_zimra_tax_id for the ZIMRA tax ID. Zoho's built-in hsn_or_sac field only exists in the India, Kenya and South Africa editions — a Zimbabwe organisation will not have it, which is why the custom field matters. If you skip both, we auto-fill the HS code and resolve the tax ID from the rate.

Create the Invoice Webhook

Zoho Books → Settings → Automation → Workflow Rules → New. Module: Invoices. Trigger: When an Invoice Is Created or Edited, condition Status Is Sent (or your preferred point of no return).

Point It at ThatFiscal

Action → Webhook → URL https://api.thatfiscal.com/webhooks/zoho, method POST, format JSON, body Invoice JSON (all fields). Add header X-Api-Key: tf_…. Sending all fields matters: the custom fields arrive in custom_field_hash and custom_fields, and line-level ones in item_custom_fields. Zoho never exposes them as plain root cf_* keys, so a hand-trimmed payload silently loses the TIN.

Repeat for Credit Notes

Second Workflow Rule on the Credit Notes module, same webhook URL and header. ThatFiscal detects the document type and fiscalises it as a credit note with the correct sign. Always raise the credit note from the original invoice so Zoho fills invoices_credited — that array is how we link back. A free-text reference_number is used only as a fallback.

Send a Test Invoice

Mark any invoice Sent. It appears in Portal → Invoices with QR + verification code. Add the QR to your Zoho template using the fields we email back, or let customers verify via the code.