FreshBooks and Zuora integration

What moves between them

The primary flow moves FreshBooks invoices and payments into Zuora. When an invoice is created or updated in FreshBooks, ml-connector receives the webhook, fetches the full invoice record via the FreshBooks API, maps the client to a Zuora Account or retrieves the existing one, and posts the invoice to Zuora as a new Invoice object. When a payment is created in FreshBooks, it flows into Zuora as a Payment record applied to the corresponding invoice. Reference data such as client information and invoice line items are pulled from FreshBooks on each sync to ensure accuracy. Zuora's response is primarily read-only for billing calculations and revenue recognition, so ml-connector does not write back to FreshBooks from Zuora; data flows one direction from accounting into billing.

How ml-connector handles it

ml-connector bridges the two OAuth models by storing both sets of credentials encrypted. On the FreshBooks side, it accepts the user-delegated token and account ID, and listens for incoming webhook POST requests with HMAC-SHA256 signature validation. FreshBooks webhooks deliver object IDs and account IDs, so ml-connector fetches the full record via the FreshBooks API to extract line items, client data, and payment terms. On the Zuora side, ml-connector exchanges Client Credentials for a bearer token, caches it until expiry, and detects the correct multi-region base URL from customer configuration. Each FreshBooks client is mapped to a Zuora Account by email or external ID; the mapping is stored and reused on subsequent invoice posts. When FreshBooks webhook delivery is slow or disabled, ml-connector can poll the FreshBooks API on a configurable schedule instead. Zuora's rate limits (50,000 RPM production, 2,500 RPM sandbox) are monitored, and HTTP 429 responses trigger exponential backoff and retry. Every record carries a full audit trail, including the original webhook payload, API calls made, and any transformation applied, so failed deliveries can be replayed when the issue is resolved.

A real-world example

A mid-market SaaS company uses FreshBooks to manage client invoicing and accounting for its cloud services business. As it matures, it migrates to Zuora for subscription billing and revenue recognition, which requires handling complex multi-year contracts, subscription amendments, and deferred revenue. Before the integration, the finance team manually copied invoice data from FreshBooks into Zuora every week, a process that introduced typos and timing delays. With FreshBooks and Zuora connected, each invoice created in FreshBooks automatically flows into Zuora within seconds. Clients appear as Accounts, invoice totals and payment terms match exactly, and the revenue recognition engine in Zuora operates on clean, authoritative data from day one. The finance team reclaims hours of manual work per week and gains confidence that both systems are always in sync.

What you can do

• •Post FreshBooks invoices to Zuora as Accounts and Invoice objects, mapped by client email or external ID.
• •Sync FreshBooks payments into Zuora as Payment records applied to the corresponding invoices.
• •Bridge FreshBooks user-delegated OAuth with Zuora Client Credentials, refreshing tokens as needed.
• •Route requests to the correct Zuora region, detect multi-region endpoints, and handle rate limits with exponential backoff.
• •Deliver a complete audit trail of every record, webhook payload, API call, and transformation for troubleshooting and replay on failure.

Questions

How does ml-connector handle the different OAuth models between FreshBooks and Zuora?

FreshBooks uses user-delegated OAuth 2.0, so ml-connector stores the user's authorization token and account ID. Zuora uses Client Credentials, so ml-connector stores the client ID and secret, exchanges them for a bearer token, and caches the token until it expires in 1 hour. Both credential sets are encrypted at rest. When a webhook arrives from FreshBooks, ml-connector validates the HMAC-SHA256 signature with the customer's FreshBooks account; when posting to Zuora, it adds the Zuora bearer token to the Authorization header.

What happens if FreshBooks webhooks are slow or disabled?

FreshBooks webhook delivery can range from seconds to several minutes. If webhooks are disabled or unreliable, ml-connector can poll the FreshBooks API on a configurable schedule to fetch new invoices and payments. Both modes support the same audit trail and error replay, so switching between webhook and polling does not require reconfiguration.

How are FreshBooks clients matched to Zuora Accounts?

ml-connector maps FreshBooks clients to Zuora Accounts by email address or external ID. The first time a client appears in an invoice, ml-connector either creates a new Zuora Account or retrieves the existing one by matching email. Subsequent invoices from the same client reuse the existing Zuora Account, so each client appears once in Zuora even if FreshBooks invoices arrive at different times.