Acumatica and Paylocity integration

What moves between them

The main flow runs from Paylocity into Acumatica. After each payroll run, ml-connector reads Paylocity pay statement totals and posts the labor cost journals into Acumatica as GL journal transactions, mapped to the matching Acumatica GL accounts and departments. Employee records flow the same direction so Acumatica headcount reflects Paylocity new hires, terminations, and rehires. Reference data such as departments and job codes is aligned so each payroll line lands on a valid Acumatica account and subaccount. Pay statements are read-only in Paylocity, and the chart of accounts lives in Acumatica, so ml-connector never writes financial entries back into payroll.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Paylocity side it runs the OAuth 2.0 client-credentials grant, caches the bearer token, and re-requests it before the one-hour expiry, scoping every call to the company ID in the path. On the Acumatica side it requests an OAuth token against the tenant instance, keeps the endpoint version in the URL aligned to the customer's ERP release so calls do not 404, and wraps every field value in the value object Acumatica requires. A Payroll Processed webhook from Paylocity carries only the process and check identifiers, so ml-connector calls the Pay Statement API to read the full totals, then maps earnings, deductions, and taxes to Acumatica GL accounts and departments before writing a balanced journal transaction. Departments and accounts are mapped first so no line posts to a missing dimension. Neither system offers an idempotency-key header, so ml-connector dedupes on the Paylocity process ID and a BullMQ jobId before posting, which prevents a replayed payroll from double-booking the ledger. Acumatica can also be polled on the LastModifiedDateTime field as a catch-up if a notification is missed. Both APIs return HTTP 429 under load, so ml-connector backs off and retries, and it tracks the annual Paylocity secret rotation so an expired credential does not become a silent outage. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-sized specialty distributor with around 400 employees runs Acumatica Cloud ERP for finance and inventory across three branches and uses Paylocity for HR and payroll. Before the integration, the accounting team exported a payroll register from Paylocity every pay period and keyed the labor totals into Acumatica by hand, then spent the start of month-end close chasing differences between HR headcount and the wage accounts in the ledger. With Acumatica and Paylocity connected, each payroll run posts into Acumatica as a balanced GL journal allocated to the branch and department it belongs to, and employee changes keep the two systems aligned. Month-end close starts with the labor accounts already reconciled, and the manual re-keying step is gone.

What you can do

• •Post Paylocity payroll totals into Acumatica as balanced GL journal transactions after every pay run.
• •Map Paylocity earnings, deductions, and taxes to the right Acumatica GL accounts, departments, and subaccounts.
• •Keep Acumatica employee records aligned with Paylocity new hires, terminations, and rehires.
• •Bridge Paylocity client-credentials OAuth with Acumatica tenant OAuth and version-locked endpoint paths.
• •Trigger on Paylocity Payroll Processed webhooks with process-ID dedup, retries, and a full audit trail on every record.

Questions

Which direction does data move between Acumatica and Paylocity?

The main flow is Paylocity into Acumatica. Payroll journal totals and employee records move from Paylocity into Acumatica as GL journal transactions and employee updates, while departments and job codes are aligned so each line lands on a valid account. Paylocity pay statements are read-only and have no GL objects, so ml-connector keeps the chart of accounts in Acumatica and never writes financial entries back into payroll.

How does the integration handle the short Paylocity token and Acumatica's version-locked endpoints?

Paylocity bearer tokens expire after one hour with no refresh flow, so ml-connector caches the token and re-requests it through the client-credentials grant before it expires. On the Acumatica side it keeps the endpoint version in every URL path matched to the customer's ERP release, because a mismatched version returns HTTP 404. Both credential sets are stored encrypted and used per request.

Does the integration rely on webhooks or polling?

It can use both. Paylocity pushes a lightweight Payroll Processed webhook that carries only the process and check identifiers, which ml-connector treats as a trigger and then calls the Pay Statement API to read the full totals. Because neither side guarantees delivery, Acumatica can also be polled on the LastModifiedDateTime field as a catch-up, and the Paylocity process ID is used to deduplicate so a replayed event does not double-post.