QuickBooks Desktop and UKG integration

What moves between them

The main flow runs from UKG into QuickBooks Desktop. After each payroll run, ml-connector polls UKG's payroll GL export and third-party-pay endpoint for labor cost journals and posts them into QuickBooks' general ledger, mapped to the cost centers and account structure that exists in your QuickBooks chart of accounts. Employee records and pay groups flow the same direction so QuickBooks employee and vendor lists stay in sync with UKG hires, terminations, and changes. Reference data such as cost centers and departments is aligned bidirectionally. GL documents in UKG are read-only, so ml-connector never writes financial entries back into payroll.

How ml-connector handles it

ml-connector stores both credential sets encrypted: the QuickBooks session credentials for the SOAP handshake and UKG's API key or OAuth token for REST calls. On the QuickBooks side it conducts the SOAP authenticate() handshake on each poll interval to obtain a fresh session GUID, then queries for modified records since the last run using ModifiedDateRangeFilter. On the UKG side it uses HTTP Basic Auth plus the scoped API keys, or renews an OAuth token before each poll since tokens expire in one hour. Cost centers and departments are mapped first so every payroll journal line references an account and cost center that already exists in QuickBooks. Because QuickBooks is pull-only and QBWC operates sequentially without parallel requests, ml-connector polls on a fixed interval tied to your payroll calendar rather than trying to push. Every record carries a full audit trail and can be replayed if a downstream update fails. QueryTimeout for large QBXML requests is approximately 60 seconds, so very large payroll runs are paged across multiple requests.

A real-world example

A regional accounting firm manages QuickBooks Desktop for a small manufacturer with 50 employees across two plants. The firm also handles payroll outsourcing via UKG, running bi-weekly payroll for both locations. Before integration, the accountant exported the payroll register from UKG every pay period, manually tallied labor costs by plant, and re-entered the totals into QuickBooks' general ledger, then spent days in month-end matching payroll GL to QuickBooks labor accounts. With QuickBooks Desktop and UKG connected, each payroll run's GL posting flows into QuickBooks automatically on the day after payroll closes, allocated to each plant's cost center, and employee adds and terminations are recorded as vendor changes in QuickBooks. Month-end close starts with payroll already reconciled.

What you can do

• •Post UKG payroll GL documents into QuickBooks Desktop's general ledger after every pay run, allocated to the correct cost centers and departments.
• •Keep QuickBooks employee and vendor records aligned with UKG hires, terminations, and rehires.
• •Map UKG cost centers and pay groups to QuickBooks' chart of accounts so labor costs land on the right GL accounts.
• •Authenticate QuickBooks via SOAP session-token handshake and UKG via HTTP Basic Auth or OAuth, and poll both on a schedule tied to your payroll calendar.
• •Maintain a full audit trail on every payroll record synced, with replay on failure and protection against duplicate GL entries.

Questions

How does the integration handle QuickBooks' requirement for an on-premises QBWC agent?

ml-connector connects to the customer's own SOAP endpoint that the QBWC agent polls. ml-connector serves that endpoint, accepts the QBWC authentication handshake, and returns session tokens. The customer's QBWC agent runs on their Windows machine on a configurable interval, and ml-connector behaves like a remote service it calls out to.

What happens if QuickBooks or the QBWC agent is not running when a poll is scheduled?

The QBWC agent will miss that scheduled interval and reconnect at the next one. ml-connector retries the connection and uses ModifiedDateRangeFilter to detect any changes that occurred while offline, so records are not lost. However, QuickBooks must be open and logged into the company file for QBWC to process requests, so the customer needs to ensure both stay running during business hours.

Does the integration handle UKG's 14-day webhook retention and one-hour OAuth token expiry?

Yes. ml-connector polls UKG on a fixed schedule rather than relying on webhooks alone, which avoids issues with the 14-day event retention window. OAuth tokens are renewed automatically before each poll since they expire in one hour. This approach ensures no payroll records are missed and credentials stay fresh.