> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dualentry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paychex Flex Integration: Setup and Sync

> Connect Paychex Flex to DualEntry to sync each payroll run as a single consolidated journal entry for earnings, taxes, and deductions.

Connect [Paychex Flex](https://www.paychex.com/) to DualEntry so each payroll run posts to your ledger as a single consolidated journal entry. The connection runs through DualEntry's payroll-data provider, which handles authentication with Paychex on your behalf. Data flows one way: Paychex Flex to DualEntry. The integration consolidates every employee's pay statement for a payroll run into one journal entry per payment, with lines for earnings, taxes, employee deductions, and employer contributions.

## Prerequisites

Confirm the following before connecting Paychex Flex:

* Admin access to both your DualEntry and Paychex Flex accounts.
* Your [chart of accounts](../core-financials/general-ledger/chart-of-accounts) in DualEntry includes the GL accounts you intend to use for payroll expense, tax expense, employee and employer benefit accounts, and a payroll clearing or accrued-payroll account.
* A vendor record in DualEntry to use as the payroll vendor (typically named "Paychex").
* A single DualEntry company that the Paychex Flex data should post to. Consolidated payroll runs in single-entity mode only (see [Current limitations](#current-limitations)).
* No classification setup is required in advance. DualEntry splits pay statement lines by **Department** and **Location** classifications automatically, creating them on first sync if they do not already exist.

## How to connect

DualEntry connects to Paychex Flex through a hosted Connect widget, so you do not generate API keys or paste credentials into DualEntry. The payroll-data provider handles authentication and returns an access token to DualEntry.

1. In DualEntry, navigate to **Company → Integrations → Paychex Flex**.
2. Choose **Connect**. DualEntry opens the Connect widget in a new window.
3. In the widget, choose **Paychex Flex** and sign in with your Paychex admin credentials.
4. Approve the data scopes requested on DualEntry's behalf.
5. After approval, the provider redirects back to DualEntry and the integration shows as **Connected**.

The first sync after a fresh connection pulls only metadata (companies, payroll vendor, pay statement items, departments) so you can finish mapping before any journal entries are written. Pay statements sync once every required mapping is complete.

If the connection later shows a **reauth** or permissions status, the Paychex authorization needs to be renewed. Reconnect from the same screen to re-run the Connect flow against the existing connection rather than creating a duplicate.

## What syncs

The integration pulls the following Paychex Flex data into DualEntry on each sync run. Paychex is the system of record; DualEntry ingests this data and does not push anything back.

| Paychex Flex data   | DualEntry record                          | Notes                                                                                                                                                                                    |
| ------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Companies           | `company` mapping                         | One Paychex company maps to one DualEntry company in single-entity mode.                                                                                                                 |
| Payroll vendor      | `vendor` mapping                          | One vendor (typically named "Paychex") stamped on every payroll journal entry line.                                                                                                      |
| Pay statement items | `pay_statement_item` to `account` mapping | Earnings, taxes, employee deductions, and employer contributions. Each unique item must map to a GL account.                                                                             |
| Departments         | classification line                       | Mapped to a configurable classification (default name: **Department**). Used to split journal entry lines by department and tag each line with the relevant classification in DualEntry. |
| Payments            | `payment` record                          | Reference data; one consolidated journal entry is created per payment.                                                                                                                   |
| Pay statements      | `pay_statement` record                    | Per-employee detail; rolled up into the consolidated journal entry, not posted individually.                                                                                             |

Pay groups, individuals, entities, and headcount are also pulled by the provider but hidden from the configuration UI for consolidated payroll. They are internal references the integration uses, not records you map.

## Map your Paychex Flex data

After connecting, DualEntry pulls Paychex Flex metadata and shows you what to map. Until every required mapping is filled in, the integration shows as not yet set up and pay statements do not post.

The mapping work breaks into three pieces. First, map the Paychex company and the payroll vendor so DualEntry knows where journal entries land and which vendor to stamp on every line. Second, map every pay statement item to a GL account so each earnings, tax, deduction, and contribution line posts to the right place. Third, optionally map departments to classifications if you want journal entry lines split by department.

### Map companies and the payroll vendor

Map the Paychex company to the DualEntry company that should receive the payroll journal entries, and map the payroll vendor to a DualEntry vendor record. The company mapping determines which DualEntry company the consolidated journal entry posts to. The payroll vendor mapping determines the vendor stamped on every line of the journal entry.

1. Open **Company → Integrations → Paychex Flex → Configuration**.
2. On the **Companies** tab, map the Paychex company to a single DualEntry company.
3. On the **Payroll vendor** tab, map the Paychex-named vendor to your DualEntry payroll vendor record.

If you skip either mapping, sync runs that depend on it fail with an explicit error in the Integration Errors log (see [Troubleshoot sync errors](#troubleshoot-sync-errors)).

### Map pay statement items to GL accounts

Each pay statement item (earnings line, tax line, employee deduction, employer contribution) must map to a DualEntry GL account before pay statements can post.

1. Open the **Pay statement items** tab. Items are grouped by category: `earnings`, `taxes`, `employee_deductions`, `employer_contributions`.
2. For each item, choose the DualEntry GL account the line should post to. Item display names follow the pattern `{category}{-Employer|-Employee}: {item name}`, for example `taxes: Federal Income Tax` or `employer_contributions-Employer: 401(k) Match`.
3. Confirm the debit/credit direction stored on each item. This controls whether the amount posts as a debit or credit on the journal entry.

If any pay statement item is unmapped when a payroll run syncs, the run is captured as an error against the relevant pay statement records and no journal entry is written for that payment until the mapping is filled in.

### Map departments to classifications

Paychex departments sync into a **Department** classification in DualEntry automatically. DualEntry auto-creates the classification and a line for each department if they do not already exist, then applies them to the journal entry via the saved mapping. This step is optional and needs no per-department setup.

If you unmap a department, or remove its classification line, that department is omitted from the journal entry, with no error, and it is not re-created on the next sync.

## How payroll runs become journal entries

Once setup is complete, each Paychex Flex payment (pay run) becomes a single consolidated journal entry in DualEntry, not one journal entry per employee. The consolidation rules:

* All pay statements that share a `payment_id` group together.
* For each unique combination of (pay statement item, classification), the integration sums amounts across employees and creates one journal entry line. For example, with eight departments and a "Salary" item, the entry has eight "Salary" lines, one per department.
* Tax items are grouped by item only, with no classification split. When **Consolidate payroll tax** is on, tax items are further consolidated by GL account into a single "Consolidated Payroll Tax" line per account.
* The journal entry is dated the payment's pay date.
* The memo follows the pattern `[Paychex Flex] Payroll {start_date} to {end_date} paid on {pay_date} ({n} employees)`.

If debits and credits do not balance after grouping, for example when rounding causes a sub-cent drift across many employees, an offset line is added against the configured payroll offset account so the journal entry posts cleanly. The offset account is configured at the organization level under integration settings; review it before going live so the offset does not land in an unexpected GL account.

The consolidated journal entry is the source of truth in DualEntry. Individual pay statement records are kept for traceability but marked as consolidated and excluded from posting. See [Journal Entries](../core-financials/general-ledger/journal-entries) for how to review the resulting entries.

## Optional: Consolidate payroll tax

By default, every tax item across a payroll run is consolidated by GL account into a single "Consolidated Payroll Tax" line per account on the journal entry. This keeps the entry compact when many tax types map to the same account, for example several state-specific income taxes all posting to the same expense account.

If you would rather see one journal entry line per tax item, for granular reporting or tax-type-level analysis, turn this off:

1. Open **Company → Integrations → Paychex Flex → Settings**.
2. Toggle **Consolidate payroll tax** off.
3. The next sync re-renders pay statements with one line per (tax item, account).

The setting affects only how tax items are grouped on the journal entry. It does not change which records are pulled from Paychex or how earnings, deductions, or contributions are grouped.

## Current limitations

The Paychex Flex integration has the following limitations today:

* **Single-entity mode only.** Consolidated payroll requires a single DualEntry company per Paychex Flex connection. Multi-entity setups (one connection mapping pay statements to multiple DualEntry companies) are not yet supported and skip pay statement processing with a warning.
* **No retroactive remapping.** Pay statements already consolidated into a journal entry do not re-post if you later change a pay statement item mapping. Resync the affected payment range to apply the new mapping.
* **Department and location classification splits only.** Pay statement classification splits use the configured department and location classifications. Splits by other classifications (such as project or class) are not applied automatically.
* **Departments match by exact name.** A Paychex department reuses an existing classification line only when the names match exactly. If the names differ, even by punctuation or case, DualEntry auto-creates a new line rather than reusing the existing one.

## Troubleshoot sync errors

When a record fails to sync, it appears in the **Integration Errors** log under **Company → Integrations → Paychex Flex**. The most common causes:

| Error                                             | Cause                                                                                                                                 | Resolution                                                                                           |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `[pay_statement_item] ... is not mapped`          | A pay statement item exists in Paychex but has no DualEntry GL account assigned.                                                      | Open the **Pay statement items** tab, assign a GL account to the unmapped item, and resync.          |
| `[pay_statement_item] ... does not exist`         | A pay statement references an item not yet pulled into DualEntry.                                                                     | Sync pay statement items before retrying the payroll run sync.                                       |
| `payroll_vendor is missing`                       | The Paychex payroll vendor is unmapped on the Configuration screen.                                                                   | Map the Paychex-named vendor to a DualEntry vendor record.                                           |
| `company mapping not found for individual ...`    | A pay statement references an individual whose Paychex company is not mapped.                                                         | Map the missing Paychex company on the Configuration screen.                                         |
| Multi-entity warning, pay statements skipped      | The connection spans multiple provider entities, which consolidated payroll does not support yet.                                     | Reduce the Paychex Flex connection to a single entity, or wait for multi-entity support.             |
| Items have different currencies in the same group | A grouping key (item plus classification) ended up with mixed currencies, typically when an employee was paid in a non-base currency. | Review the affected pay statements in Paychex, normalize the currency, and resync the payment range. |

## Result

After completing these steps, every Paychex Flex payroll run posts to DualEntry as a single consolidated journal entry, with line items per (pay statement item, department) and a balanced offset entry where needed. To verify the first run, open the consolidated entry for the latest pay date and confirm its memo reads `[Paychex Flex] Payroll ...`, that total debits equal total credits, and that each earnings, tax, deduction, and contribution line landed in the GL account you mapped. Spot-check a department split against the Paychex payroll report so you know classifications resolved as expected.

To audit the resulting payroll entries, see [Journal Entries](../core-financials/general-ledger/journal-entries). For another payroll provider that connects the same way, see the [Gusto integration](./gusto) or the [Justworks integration](./justworks). To connect additional systems, return to [Integrations](./index).