1. Pick your Zoho Region in Settings — it must match your Zoho account's data-center. Check the domain your Zoho Books opens on (e.g. books.zoho.com = Global/US, books.zoho.sa = Middle East). Even if you pick wrong, the connection self-corrects: Zoho tells the app your real data-center during login and the app remembers it.
2. Create the API app in the API console of the same region (Server-based Application) and set the Redirect URI exactly to https://crm.digitsonline.com/integrations/zoho-books/oauth/callback. If your app was created in another region's console, enable Settings → Multi-DC on it and toggle your data-center ON.
3. Paste the Client ID + Client Secret in Settings, Save, then click Connect to Zoho Books and Allow. The app captures your organisation automatically.
4. Optional — real-time sync: set a Webhook Secret in Settings and configure the same secret + this URL in Zoho Books → Developer Space → Webhooks: https://crm.digitsonline.com/api/integrations/zoho-books/webhook. For security, webhook events are rejected until a secret is set.

In the CRM, a client can have multiple contact persons (Client → Contacts tab, one marked Primary) and multiple companies (Client → Companies tab, one marked Primary). The sync always uses the primary of each:

Pull direction (Zoho → CRM): customers created in Zoho arrive as new CRM clients (company name, email, phone, website, address). Vendors are excluded — suppliers created for expense bills never appear in your client list.

• Customer link: Zoho requires every invoice to belong to a customer. If the invoice's client was never synced, the sync creates the Zoho customer first, automatically.
• One continuous numbering (CRM is the numbering authority): your CRM numbers (INV-2026-0001, …) are kept in Zoho via the "keep my number" flag — and an invoice created inside Zoho Books is assigned the CRM's next sequential number on pull and immediately renamed in Zoho to match, so both systems always share one sequence. Existing CRM invoice numbers are never overwritten by pulls.
• Invoices dated before your Zoho VAT period: Zoho refuses any tax rate on them, so the sync automatically pushes those invoices without VAT on the lines (how Zoho expects pre-period records) — current-period invoices keep their 5% VAT.
• Line items: description, quantity, rate and discount % are carried over.
• UAE VAT: each line's VAT % is matched against your Zoho organisation's tax list (e.g. the standard 5% VAT) and applied as a real Zoho tax, so totals and VAT reports are correct. If the org has no matching tax the line is pushed without tax.
• Status mapping (pull): Zoho void → CRM cancelled; partially paid → partial; draft/sent/paid/overdue map one-to-one.
• Batching: pushes are capped at 50 new invoices per click so the request can't time out — the completion popup tells you to click again for the rest.

• Approval gate: only APPROVED expenses are pushed to Zoho Books — pending or rejected expenses stay out of the books; once approved they sync on the next run.
• Approval rights: Approve / Reject is available to admins and managers (other roles see the expense but cannot approve it).
• "Purchased From" vendor list: the field is a dropdown backed by a managed vendor list — use the + button beside it to add a new vendor on the spot. The list was auto-seeded from vendor names already typed on your existing expenses.
• Vendor in Zoho: Zoho bills must belong to a vendor. The sync finds — or creates — a Zoho vendor contact from the expense's "Purchased From" value (falls back to a generic "CRM Expenses" vendor when empty).
• Client on the bill: when the expense has a client that is already synced, the bill line in Zoho carries that customer, so the client shows on the bill.
• Expense account: bill lines post to the first expense-type account in your Zoho chart of accounts. If your org has none, the sync tells you exactly that in the results.
• Fields: purchase date → bill date, item name → line description, price → amount, description → notes.
• Status mapping (pull): Zoho paid → CRM approved; void → rejected; everything else arrives as pending.

• Payments Received: a payment recorded on a CRM invoice is pushed to Zoho as a Customer Payment applied to that invoice (amount, date, method, reference) — so the invoice balance and receivables in Zoho always match the CRM. Payments recorded inside Zoho flow back, and the CRM invoice's paid/due amounts and status (partial / paid) update automatically. The invoice must be synced first — the sync orders this for you automatically.
• Credit Notes: non-draft CRM credit notes push to Zoho (with VAT lines) and are applied against the original invoice when it is synced. Zoho-created credit notes pull back — with the same numbering-authority rule as invoices (they get the CRM's next CN number and Zoho is renamed to match). Status map: Zoho closed → CRM applied, void → voided.
• Estimates / Quotes: CRM estimates push with line items, VAT, validity date and status (sent / accepted / declined); Zoho-created estimates pull back with the CRM numbering-authority rule. Zoho invoiced arrives as CRM accepted. New pushes are capped at 50 per run.
• Items (one-way): the active services in your CRM catalogue push to Zoho as service Items (name, rate, SKU/code, description, VAT) so Zoho's sales-by-item reports match the CRM. An existing Zoho item with the same name is adopted, never duplicated. Zoho items are not pulled — the CRM catalogue is the source of truth.

• Every synced record keeps a fingerprint of both sides. On each run the sync only touches records that actually changed — unchanged records are skipped (fast + no duplicates).
• Changed in CRM only → pushed to Zoho. Changed in Zoho only → pulled into the CRM.
• Changed on both sides since the last sync → the CRM version wins and the record is flagged conflict in the sync map for review.
• Deleting a synced record in the CRM does not delete it in Zoho; a later pull re-creates it in the CRM.

• Sync Now (dashboard) — runs all enabled entities in order: contacts → invoices → expenses.
• Sync by Entity buttons — run just one entity; results show in a styled popup, and any failures open the full Results & Fix Guide page.
• Automatic (hourly) — enable "automatic sync" in Settings; requires the server scheduler (cron) to be running.
• Real-time (webhooks) — with the webhook configured, changes made inside Zoho Books (contact/invoice/bill created or updated) flow into the CRM within seconds.

• Every failed record's reason is recorded. In Recent Sync Activity click Details on the run, or open the Results & Fix Guide page — it recognises the common Zoho configuration problems and shows step-by-step fixes.