QuickBooks Online and UKG integration

What moves between them

The main data flow runs from UKG into QuickBooks Online. After each payroll run, ml-connector reads UKG's GL payroll journals and posts them into QuickBooks as journal entries, mapped to the matching QuickBooks GL accounts and departments. Employee records including hires, terminations, and compensation changes flow the same direction so QuickBooks headcount and the employee roster reflect UKG master data. Cost centers and departments are aligned in both directions so payroll allocations land on valid QuickBooks dimensions. Because QuickBooks GL journals should be read-only from the payroll perspective, ml-connector does not write accounting entries back into UKG.

How ml-connector handles it

ml-connector stores both credential sets encrypted: OAuth tokens for QuickBooks (with 1-hour expiry and automatic refresh before expiration) and either Basic Auth keys or OAuth credentials for UKG (with 1-hour OAuth expiry and key rotation logic). On the QuickBooks side, ml-connector uses the realm ID to construct tenant-specific URLs and handles the SyncToken concurrency requirement on creates and updates. On the UKG side, it polls both the employee-ids endpoint (which returns only internal UUIDs) and then fetches full employee profiles per ID, managing the two-pass fetch requirement. Payroll GL journals arrive via UKG's /thirdpartypay endpoint, which already contains GL account segments and debit/credit amounts; ml-connector maps these to QuickBooks accounts by department and cost center. Because QuickBooks webhooks send only the entity ID, ml-connector follows each webhook with a GET to fetch the full record, and it uses the CDC polling endpoint as a secondary verification layer for zero-tolerance integrations. UKG's 14-day webhook retention means that for multi-week payroll cycles, ml-connector falls back to delta polling to ensure no payroll run is missed. Every record carries a full audit trail and can be replayed if a downstream QuickBooks post fails.

A real-world example

A services company with 150 employees runs UKG Workforce Now for payroll and time tracking across four cost centers, and uses QuickBooks Online for accounting and expense management. Before the integration, the finance team exported payroll registers from UKG weekly, transformed them into journal entries in a spreadsheet, and manually re-entered labor and burden costs into QuickBooks by cost center, a process that took 4 to 6 hours per week and frequently contained transposition errors. With UKG and QuickBooks Online connected, each payroll run's GL journal flows automatically into QuickBooks, allocated to the correct cost center, with employee master data updates keeping the employee roster in QuickBooks in sync. The weekly manual re-keying step is eliminated and month-end close begins with payroll and labor accounts already reconciled.

What you can do

• •Post UKG payroll GL journals into QuickBooks Online accounts after every pay run, allocated to the correct cost centers and departments.
• •Keep QuickBooks Online employee records in sync with UKG hires, terminations, and compensation changes.
• •Map UKG cost centers and departments to QuickBooks GL dimensions so payroll allocations land on valid accounts.
• •Authenticate QuickBooks Online with OAuth 2.0 and UKG with Basic Auth keys or OAuth 2.0 client credentials, refreshing tokens before expiry.
• •Poll UKG and QuickBooks on a schedule tied to your payroll cycle, with retries and a full audit trail on every record.

Questions

How does ml-connector handle QuickBooks Online's webhook and CDC polling?

QuickBooks webhooks send only the entity ID and operation, so ml-connector follows each webhook with a GET request to fetch the full record. ml-connector also uses the 30-day CDC endpoint as a secondary verification layer to ensure no changes are missed, especially for multi-week payroll cycles where QuickBooks records may fall outside the webhook window.

Why does UKG require a two-pass fetch for employees?

The /personnel/v1/employee-ids endpoint returns only internal UUIDs; ml-connector must call /personnel/v1/employees/{id} per employee to retrieve the full profile (name, cost center, compensation). ml-connector performs this two-pass fetch on initial sync and then uses delta polling to track changes, so repeat syncs are much faster.

What happens when UKG's webhook event retention expires?

UKG webhooks retain events for 14 days; if a payroll cycle is longer than 14 days or ml-connector misses a webhook, it falls back to the delta polling endpoint to ensure the payroll run is not missed. Every journal entry carries a full audit trail, so any post can be replayed if it fails.