Zoho Books and Cleo integration

What moves between them

The primary flow moves invoices and bills from Zoho Books into Cleo. On a schedule you control, ml-connector polls Zoho Books for newly created or modified invoices and bills, reads their line items and accounting dimensions, and uploads them to Cleo as EDI 810 (invoice) or 810 variant files or API payloads. Contact records from Zoho Books map to Cleo connection entities so outbound EDI documents route to the correct trading partner. The integration is unidirectional; Cleo does not write financial records back into Zoho Books.

How ml-connector handles it

ml-connector stores Zoho Books OAuth2 credentials encrypted and routes all calls to the correct regional base URL (US, EU, India, Australia, Japan, Canada, China, or Saudi Arabia) based on the region field returned in the token response. Access tokens are refreshed proactively at 55 minutes to avoid expiry mid-flow. Every Zoho Books organization ID is resolved after authentication and passed on every API call. Zoho Books invoices carry currency_id fields; ml-connector caches the currency code list so exchange rates and multi-currency transactions map correctly to Cleo. If Zoho Books webhooks are enabled, ml-connector verifies HMAC signatures using the configured webhook secret. For polling, ml-connector uses offset-based pagination and the has_more_page indicator to fetch all records. Cleo connections are matched to Zoho Books contact records by a stored mapping, so outbound EDI files are routed to the correct partner. Rate limit 429 responses are retried with exponential backoff. Every record pulled from Zoho Books and delivered to Cleo carries a full audit trail.

A real-world example

A mid-market wholesale distributor uses Zoho Books for accounting across multiple regions and Cleo to manage EDI to a large retailer customer and smaller direct suppliers. Previously, the finance team exported invoices from Zoho Books weekly, manually reformatted them into EDI 810 files, and uploaded them to Cleo. With Zoho Books and Cleo integrated, each invoice created in Zoho Books is automatically polled, translated to EDI, and delivered to Cleo within minutes. The EDI documents route to the correct partner based on the customer ID in Zoho Books, eliminating the manual export and reformatting step. Invoice discrepancies between systems vanish because there is no re-entry.

What you can do

• •Poll Zoho Books invoices and bills on a schedule you define and send them to Cleo as EDI 810 documents or API payloads.
• •Handle all eight Zoho Books regional base URLs and route calls to the correct region based on account geography.
• •Refresh Zoho Books OAuth2 tokens proactively and resolve organization IDs to ensure uninterrupted polling.
• •Map Zoho Books contact records to Cleo connections so invoices reach the correct trading partner.
• •Verify Zoho Books webhook signatures where enabled and handle both webhook push and REST polling without code changes.

Questions

Which direction does data move between Zoho Books and Cleo?

The primary flow is Zoho Books to Cleo. Invoices and bills from Zoho Books are polled, formatted as EDI transactions, and delivered to Cleo for distribution to trading partners. Cleo does not write financial records back into Zoho Books.

How does the integration handle Zoho Books' regional infrastructure and OAuth2 tokens?

ml-connector resolves the customer's region from the token response and routes all subsequent calls to the matching regional base URL. OAuth2 access tokens are refreshed proactively at 55 minutes before expiry to ensure continuous polling. The organization ID, which is required on every Zoho Books call, is resolved during authentication.

What happens to invoices with multiple currencies or complex account mappings?

ml-connector caches Zoho Books currency codes and exchange rates so multi-currency invoices map correctly. Contact records in Zoho Books match to Cleo connections via a stored mapping, ensuring invoices route to the right partner and account dimensions are preserved in the EDI output.