Xero and UKG integration

What moves between them

The primary data flow moves from UKG into Xero. After each payroll run, ml-connector reads UKG's GL payroll journal entries and posts them into Xero's general ledger as manual journal entries, mapped to the matching Xero GL accounts and cost centers from UKG's cost center master data. Employee records including demographic details and compensation information flow from UKG into Xero's contact base so Xero reflects current headcount, hires, and terminations. Reference data such as cost centers and payment groups is aligned so every payroll journal line references a GL account and cost center that already exists in Xero. GL data is read-only in UKG, so ml-connector never writes financial entries back to payroll.

How ml-connector handles it

ml-connector stores both credential sets encrypted and can use either HTTP Basic Auth with the two custom UKG API keys or OAuth2 client credentials on the UKG side, refreshing the bearer token when it expires after 1 hour. On the Xero side it handles OAuth2 token refresh on 30-minute expiry and validates the Xero-tenant-id header requirement for multi-org deployments. UKG's employee ID endpoint returns internal UUIDs that require a second call per employee to retrieve the full profile, so ml-connector batches these two-pass fetches and caches the results. Cost centers and accounts are mapped first so every payroll journal line references a GL account in Xero that already exists. Because both systems support webhooks, ml-connector can receive near real-time events from UKG Webhooks Premium and confirm successful delivery to Xero, though it also implements secondary polling on UKG's delta endpoint /personnel/v1/employees/changed for zero-tolerance integrations where 14-day webhook retention is not sufficient. Xero's 60 requests per minute rate limit and 5 concurrent call constraints are respected with intelligent queuing. Every record carries a full audit trail and can be replayed if a downstream journal post fails.

A real-world example

A mid-sized professional services firm runs Xero for accounting and finance across three regional offices, and uses UKG for payroll processing and HR. Before the integration, the finance team manually exported payroll GL journals from UKG each pay period and entered the totals into Xero by hand, mapping each journal line to the correct office and department code. This manual process created reconciliation delays and month-end close took extra days chasing differences between what payroll reported and what appeared in the ledger. With Xero and UKG connected, each payroll run's GL journal flows into Xero automatically, with cost centers pre-mapped to the correct regional office codes, and employee updates keep contact records current. Month-end close begins with labor accounts already reconciled, and the re-keying step is eliminated.

What you can do

• •Post UKG payroll GL journal entries into Xero's general ledger after every pay run, allocated to the correct accounts and cost centers.
• •Keep Xero contact records aligned with UKG employee hires, terminations, rehires, and demographic updates.
• •Map UKG cost centers, pay groups, and compensation details to Xero GL accounts and tracking categories so payroll lands on valid dimensions.
• •Authenticate Xero with OAuth2 and UKG with HTTP Basic Auth or OAuth2, handling token refresh and credential encryption.
• •Sync on a schedule tied to your payroll calendar, with webhook support, polling fallback, retries, and a full audit trail on every record.

Questions

Which direction does data move between Xero and UKG?

The main flow is from UKG into Xero. Payroll GL journals and employee records move from UKG into Xero, while cost centers and accounts are aligned so payroll allocations land on valid Xero dimensions. Xero's general ledger is read-only from UKG, so ml-connector does not write financial entries back into payroll.

How does the integration handle UKG's two authentication schemes and 1-hour token expiry?

ml-connector supports both HTTP Basic Auth with the US-CUSTOMER-API-KEY and US-USER-API-KEY headers, and OAuth2 client credentials flow with automatic token refresh. OAuth tokens are refreshed when they approach the 1-hour expiry, and Basic Auth credentials are stored encrypted. This ensures authentication is never a blocker for payroll syncs.

Does UKG's two-pass employee fetch and 14-day webhook retention affect sync reliability?

Yes. UKG's employee ID endpoint returns only internal UUIDs, so ml-connector batches a second call to each ID to retrieve the full profile. For webhook reliability, ml-connector implements secondary polling on UKG's /personnel/v1/employees/changed delta endpoint to ensure zero-tolerance integrations are not affected by the 14-day webhook retention window.