FreshBooks and Gusto integration

What moves between them

Payroll expense records flow from Gusto into FreshBooks. After each payroll run, ml-connector reads the Gusto payroll with its employee compensations, pay amounts, and earning types, then writes corresponding entries into FreshBooks as bills (if vendor-based) or expenses (if direct spend). The direction is one-way: FreshBooks accounting does not feed back into Gusto payroll. Reference data such as employee mappings to FreshBooks vendors and earning types to expense categories is configured once and reused for every subsequent payroll cycle. Payroll events from Gusto arrive via webhook; ml-connector also polls as a fallback to catch any webhooks that did not arrive within the expected window.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Gusto side, it accepts the company-scoped OAuth token after a human user authorizes the integration, and it refreshes the access token every 2 hours when the 10-minute expiry window approaches (Gusto tokens expire in 2 hours but must be refreshed before expiry to avoid outages). On the FreshBooks side, it uses the user-delegated OAuth token scoped to the specific FreshBooks account, since FreshBooks does not support Client Credentials. Both systems support webhooks, so ml-connector listens for Gusto payroll events and FreshBooks updates. When a Gusto payroll is marked paid, ml-connector reads the associated compensations and pay amounts, then creates bill or expense records in FreshBooks, mapped to the correct vendor (by employee) and expense account (by earning type). Dollar amounts are handled as string decimals to match Gusto's API contract. If a webhook for a payroll event is missing or delayed beyond the expected window, ml-connector polls Gusto for recent payroll cycles so no pay run is skipped. Duplicate payroll entries are avoided by tracking the Gusto payroll ID and only creating entries once per payroll cycle. Every record carries a full audit trail and can be replayed if the downstream FreshBooks write fails.

A real-world example

A small professional services firm uses FreshBooks to track project invoices and operating expenses, and Gusto to run payroll for 20 contractors and 5 W-2 employees across two offices. Before the integration, the accounting manager downloaded the payroll summary from Gusto each pay period, added up the total cost per employee or department, and manually created expense entries in FreshBooks so the profit and loss statement would reflect actual labor spend. The process took 30 minutes per pay cycle and was error-prone when employees were added or removed. With FreshBooks and Gusto connected, each payroll run automatically creates the corresponding expense entries in FreshBooks, allocated to the right vendor or cost center. The accounting manager now spends 5 minutes verifying the entries instead of 30 minutes entering them by hand.

What you can do

• •Read completed Gusto payroll runs and create corresponding bill or expense entries in FreshBooks, mapped by employee and earning type.
• •Authenticate FreshBooks with user-delegated OAuth and Gusto with company-scoped OAuth, handling both token refresh cycles.
• •Listen to Gusto payroll webhook events and FreshBooks updates, with polling-based fallback to ensure no payroll records are missed.
• •Map Gusto employee compensations to FreshBooks vendors or bill line items, and earning types to expense categories.
• •Track payroll ID and audit every record so duplicate entries are avoided and failed writes can be replayed.

Questions

Does ml-connector create entries in FreshBooks for every payroll run, or only when there are changes?

ml-connector creates entries when a Gusto payroll is marked paid, reflecting the actual compensation amounts and earning types from that payroll cycle. If Gusto recalculates payroll (for example, to correct a tax withholding), ml-connector tracks the payroll ID to avoid creating duplicate entries in FreshBooks.

How are Gusto employees and earning types mapped to FreshBooks vendors and expense categories?

You configure the mapping once in ml-connector: which Gusto employees correspond to which FreshBooks vendors or bill payees, and which Gusto earning types (salary, hourly, bonus, commission, etc.) correspond to which FreshBooks expense accounts. The mapping is reused for every payroll cycle, so changes to the mapping take effect on the next payroll run.

What happens if the Gusto or FreshBooks APIs are temporarily unavailable during a payroll sync?

ml-connector retries the Gusto read with exponential backoff and jitter. If the FreshBooks write fails, the payroll record is tracked and can be replayed once the API is back up. Every record carries an audit trail showing the timestamp, the Gusto payroll ID, and the FreshBooks entry ID so you can verify the sync completed correctly.