QuickBooks Desktop and Gusto integration

What moves between them

Employee records flow from Gusto into QuickBooks Desktop whenever an employee is created, onboarded, or terminated in Gusto. Payroll journal entries flow from Gusto after each payroll cycle: ml-connector receives a payroll processed webhook from Gusto, reads the calculated earnings and deductions, maps them to QuickBooks Desktop employee records and accounts, and posts the journal entries into the general ledger. The mapping ensures each payroll entry references a valid employee and account in QuickBooks Desktop. Reference data such as job titles and compensation types are stored as QuickBooks Desktop items or custom fields to support audit trails.

How ml-connector handles it

ml-connector registers a webhook with Gusto to receive payroll and employee events. When an event arrives, ml-connector verifies the HMAC-SHA256 signature using the shared subscription token, decodes the employee or payroll record, and determines whether to insert, update, or terminate the record in QuickBooks Desktop. For employees, it creates or updates a QuickBooks Desktop Employee record with the Gusto employee ID stored in a custom field to allow future lookups. For payroll entries, it reads the Gusto payroll's earning and deduction line items, maps each to a QuickBooks Desktop account, and constructs a journal entry to post the totals. Before any modification, ml-connector queries QuickBooks Desktop to fetch the current EditSequence version counter, includes that version in the QBXML request, and retries with an updated version if the modification is rejected due to a concurrent change. Gusto OAuth tokens expire every 2 hours, so ml-connector refreshes the access token proactively before expiry and stores the single-use refresh token securely. The integration respects Gusto's 200-request-per-minute rate limit and backs off if 429 responses are encountered. All records are logged with timestamp, Gusto source ID, and QuickBooks Desktop transaction ID for audit and replay.

A real-world example

A small professional services firm runs QuickBooks Desktop for accounting on a Windows machine and Gusto for payroll and employee benefits in the cloud. Before integration, after each biweekly payroll run, the finance manager exports gross pay and tax amounts from Gusto, creates a manual journal entry in QuickBooks Desktop to record payroll expense, and updates the employee master with termination dates and role changes by hand. With Gusto and QuickBooks Desktop connected, each payroll automatically posts a journal entry allocating salary expense and payroll taxes to the correct accounts, employee hires and terminations sync from Gusto to QuickBooks Desktop, and the firm's month-end close completes hours faster because payroll records are already reconciled.

What you can do

• •Post Gusto payroll earnings, deductions, and tax withholdings as journal entries into QuickBooks Desktop general ledger after each pay cycle.
• •Sync Gusto employee records into QuickBooks Desktop, including new hires, role changes, and terminations.
• •Store Gusto employee ID and payroll metadata as custom fields in QuickBooks Desktop to support lookup and audit.
• •Handle QuickBooks Desktop EditSequence versioning to prevent duplicate journal entries from concurrent modifications.
• •Receive Gusto payroll and employee events via webhook, verify HMAC-SHA256 signatures, and refresh OAuth2 tokens before expiry.

Questions

How does ml-connector handle the EditSequence version counter in QuickBooks Desktop?

ml-connector always queries the current EditSequence value from QuickBooks Desktop before modifying any record. It includes that version in the QBXML modification request. If a concurrent change occurs on the customer's machine, QuickBooks Desktop returns an error; ml-connector then re-queries the updated version and retries. This prevents lost updates and duplicate entries.

What happens if the QuickBooks Desktop machine or QBWC agent is offline?

If the QBWC agent is not running or the QuickBooks Desktop company file is closed, ml-connector's SOAP requests will timeout. ml-connector retries with exponential backoff over several minutes. If the machine is offline for an extended period, the integration queues pending employee and payroll records until the agent reconnects, then processes them in order.

Does ml-connector support multi-company QuickBooks Desktop setups?

QuickBooks Desktop QBWC operates on a single company file per connection. To integrate with multiple QuickBooks Desktop companies, you must register separate QBWC agents, one per company file. Gusto supports multi-company through separate OAuth tokens per company, so ml-connector can route each Gusto company to its corresponding QuickBooks Desktop QBWC registration.