FreshBooks and Cin7 integration

What moves between them

The main data flow runs from FreshBooks to Cin7 Core. FreshBooks invoices are mapped to Cin7 sales orders, invoice payments trigger SalePayment records, and FreshBooks journal entries post to Cin7 chart of accounts. Bill payments and expense records from FreshBooks flow into Cin7 purchase-related GL entries. The sync is event-driven on FreshBooks' side (webhooks push changes) and can be supplemented with polling on Cin7 (pulling Cin7 sales and purchase records to confirm receipt). Financial statuses are not pushed back upstream - Cin7 is the system of record for order state after invoice creation.

How ml-connector handles it

ml-connector stores both credential sets encrypted: the FreshBooks OAuth 2.0 refresh token to request new access tokens on expiry, and the Cin7 API keys for every request. On the FreshBooks side it listens for webhook events (invoice.create, invoice.update, payment.create, payment.delete, bill.create) and parses the HMAC-SHA256 signature to verify authenticity, refreshing the OAuth token when the API returns 401. Invoices are mapped to Cin7 sales by extracting line items and client references; payments become SalePayment records linked to the sale. Bill payments and FreshBooks expenses map to Cin7 purchases in INVOICE or RECEIVE approach, with line-item costs allocated to matching chart of accounts. Because FreshBooks status fields (invoice.status, payment.status) are read-only, ml-connector treats them as informational only and does not attempt to update FreshBooks from Cin7. The Cin7 API keys are rotatable, so ml-connector accepts new keys per customer without code changes. Every record carries a full audit trail and can be replayed if a downstream Cin7 call fails.

A real-world example

A product business uses FreshBooks for invoicing and expense tracking while running Cin7 Core for inventory management and order fulfillment. Before the integration, each FreshBooks invoice was manually entered into Cin7 as a sales record, and bill payments were re-keyed into the purchase module. The finance team spent hours every month reconciling which invoices had been entered and which had not, and payables aging reports diverged between the two systems. With FreshBooks and Cin7 connected, each invoice posted to FreshBooks appears in Cin7 as a sales record within minutes, payments automatically create matching SalePayment records, and bill payments flow directly into the purchase GL. Month-end reconciliation is reduced to a spot check, and duplicate entries are eliminated.

What you can do

• •Map FreshBooks invoices to Cin7 Core sales records with line items and client details from both systems.
• •Post FreshBooks invoice payments as Cin7 SalePayment records to track cash receipt against each sale.
• •Flow FreshBooks bill payments and expenses into Cin7 purchase GL entries allocated to the correct chart of accounts.
• •Bridge FreshBooks OAuth 2.0 user-delegated tokens with Cin7 API key authentication on every request.
• •Ingest FreshBooks webhook events, verify HMAC signatures, and replay failed Cin7 postings with a full audit trail.

Questions

How does ml-connector handle FreshBooks OAuth 2.0 user delegation if Cin7 uses API keys?

ml-connector stores both credential sets separately and encrypted. FreshBooks credentials are the OAuth 2.0 refresh token, which ml-connector exchanges for a new access token when the old one expires or returns a 401. Cin7 credentials are the two API key headers, which ml-connector includes on every Cin7 request. The user authorizes FreshBooks once during setup, and Cin7 keys are created and rotated independently through the Cin7 account.

What happens if a FreshBooks webhook fails to post to Cin7?

ml-connector receives the webhook, verifies its HMAC-SHA256 signature against the shared secret, parses the invoice or payment details, and attempts to post the corresponding record to Cin7. If the Cin7 call fails (network error, rate limit, or API error), ml-connector stores the failure with a full audit trail and retries on an exponential backoff schedule. The same invoice can be replayed into Cin7 multiple times if needed, and ml-connector uses idempotency keys to deduplicate duplicate sends.

Are FreshBooks invoice status changes reflected in Cin7?

No. FreshBooks status fields on invoices and payments are read-only - the system computes them based on invoice and payment state. ml-connector does not push status updates back to FreshBooks. Instead, ml-connector treats status as informational metadata and focuses on moving the financial records (line items, amounts, GL codes) into Cin7, where Cin7 becomes the system of record for order state after initial creation.