FreshBooks and ServiceTitan integration

What moves between them

Service invoices and payments flow from ServiceTitan into FreshBooks. When a technician completes a job and bills the customer in ServiceTitan, ml-connector reads the invoice, maps the service items to FreshBooks items, maps the customer to a FreshBooks client, and writes the invoice as a journal entry or bill in FreshBooks. Payments received in ServiceTitan are synced to FreshBooks payment records. Expenses and parts purchases in ServiceTitan can flow to FreshBooks bills if the vendor is already registered. The primary direction is ServiceTitan to FreshBooks; FreshBooks invoices do not flow back into ServiceTitan.

How ml-connector handles it

ml-connector stores the FreshBooks user-delegated OAuth2 token and ServiceTitan client credentials (Client ID, Secret, App Key, Tenant ID) encrypted and refreshes them on 401 responses. FreshBooks authenticates via authorization code grant, so ml-connector stores the refresh token and obtains a new access token when needed. ServiceTitan client-credentials tokens expire every 15 minutes and are cached to avoid re-requesting on each call. ml-connector polls ServiceTitan webhooks or reads its invoice and payment endpoints on a schedule (typically daily or after each job completion). It maps ServiceTitan customers to FreshBooks clients by email or by creating a client if one does not exist. Service items in ServiceTitan are matched to FreshBooks items by SKU or name. Payments received are posted as payment records, with the customer and amount reconciled. ServiceTitan rate limits (60 calls per second) are respected via backoff, and failed calls are retried with exponential backoff. Every synced invoice and payment carries an audit trail and can be replayed if a downstream FreshBooks API call fails.

A real-world example

A mid-sized plumbing and HVAC service company runs ServiceTitan to dispatch technicians, schedule jobs, and bill customers. They also use FreshBooks to manage accounts receivable and monthly close-outs. Before the integration, the office manager exported service invoices from ServiceTitan each week, created corresponding invoice records in FreshBooks by hand, and manually matched payments received in ServiceTitan to payments recorded in FreshBooks. Months with high job volume created a backlog and month-end reconciliation took several days of manual matching. With ServiceTitan and FreshBooks connected, each service invoice written in ServiceTitan flows automatically to FreshBooks' invoice ledger, and payments received sync without manual re-entry. The accounts receivable balance now matches between the two systems in real time, and month-end close is reduced from days to hours.

What you can do

• •Sync service invoices from ServiceTitan into FreshBooks invoices, mapped to matching customers and line items.
• •Post payments received in ServiceTitan to FreshBooks payment records, keeping accounts receivable balanced.
• •Map ServiceTitan vendors and parts to FreshBooks vendors and items, so purchase expenses reconcile across both systems.
• •Authenticate FreshBooks via OAuth2 user-delegated grant and ServiceTitan via OAuth2 client-credentials, handling token refresh and expiry.
• •Poll ServiceTitan on a schedule with retries, full audit trail, and error replay on every synced record.

Questions

How does ml-connector handle the different OAuth2 grant types between FreshBooks and ServiceTitan?

FreshBooks requires OAuth2 authorization code grant (user-delegated), which requires a user to authorize ml-connector once, after which ml-connector stores and refreshes the refresh token. ServiceTitan uses OAuth2 client-credentials grant, which requires only Client ID and Client Secret. ml-connector stores both credential sets encrypted and refreshes each independently on 401 responses.

Do service invoices flow both directions, or only from ServiceTitan to FreshBooks?

The primary direction is ServiceTitan to FreshBooks. Service invoices created in ServiceTitan sync into FreshBooks as invoices or journal entries. FreshBooks invoices do not flow back to ServiceTitan; they serve as the accounting record once the service is billed.

What happens if a ServiceTitan customer or item does not exist in FreshBooks when an invoice syncs?

ml-connector creates a matching FreshBooks client if the customer does not exist, using the customer email and name from ServiceTitan. Items are matched by SKU or name; if no match is found, ml-connector can create a new item in FreshBooks or flag the record for manual review, depending on your configuration.