QuickBooks Online and Deel integration

What moves between them

The primary flow is Deel into QuickBooks Online. After each Deel payroll run, ml-connector reads the payroll summary, extracts net-pay distributions and liability accruals per employee and department, and posts journal entries into QuickBooks' general ledger mapped to the corresponding accounts and classes. Employee contracts and employee data from Deel are synced into QuickBooks as vendor records or timekeeping entries for labor tracking. Reference data such as departments and classes are aligned in both directions so payroll allocations land on valid QuickBooks dimensions. GL entries are written once per pay cycle and can be replayed if a write fails, but Deel invoice and payroll summary data is read-only from the QuickBooks side.

How ml-connector handles it

ml-connector stores Deel's API token and OAuth2 credentials encrypted, refreshes the QuickBooks access token when a call returns 401, and handles the Deel refresh token rotation every 89 days to avoid expiry. It accepts the Deel Organization Token or user OAuth scopes at setup time and validates that the token has both payroll and accounting read permissions. Because Deel publishes real-time webhook events, ml-connector can subscribe to contract and employee lifecycle events to trigger syncs, but also polls the Deel API on a payroll-calendar schedule to catch any missed events or to support customers without webhook configuration. When writing journal entries to QuickBooks, ml-connector batches multi-employee payroll summaries into per-account GL entries, fetches the current SyncToken from QuickBooks before each write to avoid concurrency errors, and retries with exponential backoff if the write times out or hits rate limits. Deel rate limits return HTTP 429 with a Retry-After header, so ml-connector honors that header and backs off. The Deel API is scoped at token creation time, so a token may have only accounting:read or payroll:read; ml-connector validates the token scope at setup and alerts if required scopes are missing. Every record carries a full audit trail and can be replayed if a downstream write fails.

A real-world example

A mid-market services firm with contractors and full-time employees across three countries runs Deel for payroll and EOR compliance, and QuickBooks Online for invoice and expense tracking. Before the integration, the finance team exported Deel's payroll runs every month, calculated the GL entries by hand (one per country, with net pay to bank accounts and payroll tax liabilities to liability accounts), and posted them into QuickBooks, then cross-checked employee counts between Deel and QuickBooks to catch missing contractors. With Deel and QuickBooks connected, each Deel payroll run automatically posts its GL entries into QuickBooks matched to the correct accounts per country, and new contracts or terminated employees in Deel trigger a sync that updates QuickBooks so headcount is always aligned. Month-end close starts with payroll GL entries already posted and validated, and the manual entry step is gone.

What you can do

• •Post Deel payroll GL entries into QuickBooks Online after every pay run, matched to the correct general ledger accounts and classes.
• •Sync Deel employee contracts and lifecycle events (new hire, termination, rehire) into QuickBooks as vendor or employee records.
• •Map Deel departments and cost centers to QuickBooks classes so payroll expenses land on the correct account dimensions.
• •Handle OAuth2 refresh token rotation for both QuickBooks and Deel, and retry failed GL writes if a network timeout occurs.
• •Verify Deel webhook signatures and subscribe to real-time payroll events, or poll on a schedule tied to your pay calendar.

Questions

Does ml-connector write to Deel, or only read?

ml-connector reads from Deel (contracts, employees, invoices, payslips, and payroll summaries) and writes to QuickBooks Online (journal entries). Deel payroll data is read-only from the integration side; ml-connector never posts payroll inputs or modifies Deel contracts.

How does ml-connector handle the different OAuth2 token lifetimes between QuickBooks Online and Deel?

QuickBooks access tokens expire in 1 hour and refresh tokens rotate every 24 to 26 hours, requiring a re-auth if the refresh token chain breaks. Deel access tokens expire after 30 days and refresh tokens after 90 days as single-use grants. ml-connector stores both token sets encrypted, proactively refreshes them before expiry, and alerts if either token refresh fails so re-authentication can be triggered before a sync fails.

Can the integration use Deel's real-time webhooks instead of polling?

Yes. If Deel webhooks are enabled on your account, ml-connector can subscribe to contract and employee lifecycle events to trigger immediate syncs instead of polling on a schedule. This reduces latency for new hire or termination data, but ml-connector still polls the payroll summary on a calendar cadence to catch any missed webhook events.