Which direction does data move between FreshBooks and Cleo?

The main flow is from FreshBooks into Cleo. Invoices and bills are transformed into EDI transactions and placed into Cleo folders for routing to trading partners. Payments flow as EDI 820 transactions. FreshBooks status is read-only and computed by FreshBooks, so ml-connector does not write status or financial entries back to FreshBooks from Cleo.

Why does the integration use polling if FreshBooks supports webhooks?

FreshBooks webhooks are valuable for real-time acceleration but are not guaranteed to be real-time and can range from seconds to several minutes in delivery. ml-connector uses webhooks when available but relies on scheduled polling as the authoritative sync mechanism to ensure no transactions are missed, giving you a choice of sync frequency tied to your business cycle.

How does the integration handle FreshBooks OAuth 2.0 user-delegated tokens?

ml-connector uses the Authorization Code grant flow to obtain a user-delegated token on behalf of the FreshBooks user, stores it encrypted, and refreshes it before expiry. This matches FreshBooks requirement that OAuth be user-delegated, not Client Credentials. Granular scopes are applied per FreshBooks resource.

FreshBooksCleo

FreshBooks and Cleo integration

FreshBooks manages your accounting and invoicing. Cleo manages B2B/EDI orchestration and supply chain transactions. Connecting the two keeps your trading partner transactions flowing into FreshBooks without re-keying and moves FreshBooks invoices and bills into Cleo for EDI distribution to suppliers and customers. ml-connector bridges the two APIs, handles the different authentication schemes, and delivers transactions reliably on a schedule you control.

How FreshBooks works

FreshBooks exposes invoices, bills, bill vendors, payments, expenses, chart of accounts, and items through cloud REST APIs at https://api.freshbooks.com under the /accounting/account/<accountId> and /timetracking/business/<businessId> namespaces. Accounts authenticate with OAuth 2.0 user-delegated tokens (not Client Credentials), acquired via Authorization Code flow at https://auth.freshbooks.com/oauth/authorize. FreshBooks pushes transaction events via webhooks with HMAC-SHA256 signatures, though webhook delivery is not real-time and can range from seconds to several minutes. Scopes are granular per resource, and invoices and payments have read-only status fields.

How Cleo works

Cleo Integration Cloud is a cloud-native EDI and B2B integration platform at https://YOURTENANT.cleointegration.com/api, accessible via OAuth 2.0 password grant tokens (resource owner password credentials grant) to exchange username and password for short-lived bearer tokens. Cleo exchanges EDI transactions and API payloads with trading partners through Folders and Files, with pull-based polling via REST. Outbound webhooks are available via HTTP actions configured in CIC Studio by a tenant admin, but programmatic webhook subscription is not available through the self-service API. Cleo is integration middleware, not a finance system, so invoices and purchase orders flow through as EDI transactions or API payloads.

What moves between them

The main flow runs from FreshBooks into Cleo. ml-connector reads FreshBooks invoices, bills, and payments and maps them into Cleo as EDI 810 (invoice), 850 (purchase order), and 820 (payment) transactions. Cleo then routes these transactions to trading partners via EDI or API. Reference data such as vendors, customers, and chart of accounts can align in both directions. FreshBooks payments and status are read-only, so ml-connector never writes financial entries back to FreshBooks from Cleo.

How ml-connector handles it

ml-connector obtains a FreshBooks user-delegated OAuth token via the Authorization Code flow and a Cleo tenant bearer token via the password grant flow, then stores both encrypted. It polls FreshBooks at intervals you define for new or updated invoices, bills, and payments, and transforms them into Cleo EDI transaction format (850, 810, 820) based on document type and direction. FreshBooks webhooks for invoice.create, invoice.update, bill.create, bill.update, payment.create, and payment.update accelerate synchronization when available, but polling provides a fallback since webhook delivery is not guaranteed real-time. Because FreshBooks status fields are read-only and computed by the system, ml-connector reads status at sync time but does not attempt to write it back. Cleo file placement and folder routing are configured per customer; ml-connector respects those folder paths and uses Cleo's API to list, retrieve, and archive files. Retries handle rate limits and temporary API failures, and every transaction carries a full audit trail with the originating FreshBooks document ID.

A real-world example

A small-to-medium distribution company uses FreshBooks for invoicing and accounting and Cleo to manage EDI with ten key suppliers and two major customers. Before the integration, the operations team exported invoices from FreshBooks weekly and re-entered supplier purchase orders and customer shipment confirmations into FreshBooks by hand, then reconciled the documents in both systems monthly. With FreshBooks and Cleo connected, supplier invoices arrive in FreshBooks automatically from Cleo as they come through EDI, and FreshBooks invoices are pushed into Cleo EDI format and routed to customers without manual data entry. Reconciliation is faster, and the manual keying step is eliminated.

What you can do

Map FreshBooks invoices and bills into Cleo as EDI 810 (invoice) and 850 (purchase order) transactions, routed to the correct trading partner folder.
Sync FreshBooks payments into Cleo as EDI 820 (payment) transactions with full remittance detail.
Monitor FreshBooks webhooks for real-time transaction events and fall back to scheduled polling for reliability.
Authenticate FreshBooks with OAuth 2.0 user-delegated tokens and Cleo with OAuth 2.0 password grant tokens, managing both token refreshes.
Read-only respect FreshBooks computed status fields, with full audit trail on every transaction between FreshBooks and Cleo.

Questions

Which direction does data move between FreshBooks and Cleo?: The main flow is from FreshBooks into Cleo. Invoices and bills are transformed into EDI transactions and placed into Cleo folders for routing to trading partners. Payments flow as EDI 820 transactions. FreshBooks status is read-only and computed by FreshBooks, so ml-connector does not write status or financial entries back to FreshBooks from Cleo.
Why does the integration use polling if FreshBooks supports webhooks?: FreshBooks webhooks are valuable for real-time acceleration but are not guaranteed to be real-time and can range from seconds to several minutes in delivery. ml-connector uses webhooks when available but relies on scheduled polling as the authoritative sync mechanism to ensure no transactions are missed, giving you a choice of sync frequency tied to your business cycle.
How does the integration handle FreshBooks OAuth 2.0 user-delegated tokens?: ml-connector uses the Authorization Code grant flow to obtain a user-delegated token on behalf of the FreshBooks user, stores it encrypted, and refreshes it before expiry. This matches FreshBooks requirement that OAuth be user-delegated, not Client Credentials. Granular scopes are applied per FreshBooks resource.

Connect FreshBooks and Cleo

Free to use. Add your credentials, ping your real systems, and see if we fit.

Get started