📒 Guide to the payroll journal

The payroll journal gives you each payroll funding as a balanced set of general ledger entries: debit lines for what payroll cost you, and credit lines for where the money came from. Every line carries the GL code your company has mapped to it, so you can post a funding to your accounting system without re-mapping anything on your side.

It returns the same data, with the same GL codes, as the Payroll Journal report in Everee. People in your company who download that report and an integration that uses this API always see the same numbers.

It sits alongside the other payroll cost endpoints:

• The cost segments roll payroll up by cost center for a pay period or pay date. Use them to invoice or report by client, job, or project.
• The payroll journal organizes payroll by funding, as debits and credits with GL codes. Use it to post payroll to your general ledger.

How do I retrieve a journal?

You retrieve a journal in two steps. First list your fundings, then retrieve the journal of the one you want:

GET https://api.everee.com/integration/v1/payroll-costs/journal/fundings?start-date=2026-10-01&end-date=2026-10-31

GET https://api.everee.com/integration/v1/payroll-costs/journal/fundings/123456

A funding is the transfer of money that covers one or more payments. Each funding's journal balances on its own, so you can post it as one journal entry and be done with it. You never have to wait for another funding, or combine fundings, to get a balanced entry.

A funding's fundingId is a string. Treat it as an opaque value: store it and send it back exactly as you received it. Most integrations keep track of the fundingId of every funding they've already posted. Each time they run, they list the fundings since their last run and retrieve the journal of each new one.

A funding's status is one of:

A funding can still fail after it's submitted. If you'd rather not post a journal until the money has been funded, wait until the funding's status is FUNDED. We may add statuses in the future, so make sure your integration can handle a status it doesn't recognize.

The date range filters on the funding date, which is the date the money for the payments is funded, not the pay date.

How does paging work?

The list of fundings is paginated with a cursor, like the Payment Data API.

• limit sets the page size. It defaults to 25 and can be up to 100.
• Each response includes hasNextPage and, when there are more fundings, a nextCursor.
• To get the next page, send the same request with after set to that nextCursor. Treat the cursor as an opaque value: pass it back exactly as you received it.
• Keep going until hasNextPage is false.

Fundings are returned in a stable order, so a funding is never repeated or skipped as you page. A funding created while you're paging through a range appears on a later page.

Paging only moves forward, so hasPreviousPage is always false. Responses don't include a total count.

{
  "items": [
    {
      "fundingId": "123456",
      "fundingDate": "2026-10-14",
      "status": "FUNDED",
      "fundingAmount": { "amount": "4784.25", "currency": "USD" }
    }
  ],
  "pageSize": 1,
  "hasNextPage": true,
  "hasPreviousPage": false,
  "nextCursor": "MTIzNDU2"
}

The fundingAmount is the cash funding line of the funding's journal: the money funded for its payments. Use it to decide whether a funding is worth retrieving. The journal's debit and credit totals are on the journal itself.

What does a journal look like?

A journal is the funding's details, its totals, and the lines that make it up. Here's the journal of a small funding with two wage lines, two employer taxes, a benefit that Everee doesn't remit, and the cash funding. All of the wages are for the "Sales" department.

{
  "fundingId": "123456",
  "fundingDate": "2026-10-14",
  "status": "FUNDED",
  "totalDebits": { "amount": "4994.25", "currency": "USD" },
  "totalCredits": { "amount": "4994.25", "currency": "USD" },
  "lines": [
    {
      "category": "GrossPay",
      "side": "DEBIT",
      "transactionType": "REGULAR_HOURLY",
      "transactionDetail": "",
      "glCode": "6000",
      "workLocationState": "UT",
      "workLocationName": "Salt Lake Office",
      "approvalGroupName": null,
      "costCenters": [{ "slot": 1, "typeKey": "dept", "value": "Sales" }],
      "amount": { "amount": "4000.00", "currency": "USD" }
    },
    {
      "category": "GrossPay",
      "side": "DEBIT",
      "transactionType": "FIELD_HOURS",
      "transactionDetail": "Field Hours",
      "glCode": "6010",
      "workLocationState": "UT",
      "workLocationName": "Salt Lake Office",
      "approvalGroupName": null,
      "costCenters": [{ "slot": 1, "typeKey": "dept", "value": "Sales" }],
      "amount": { "amount": "500.00", "currency": "USD" }
    },
    {
      "category": "EmployerTaxes",
      "side": "DEBIT",
      "transactionType": "Social Security (ER)",
      "transactionDetail": "Social Security (ER)",
      "glCode": "6200",
      "workLocationState": "UT",
      "workLocationName": "Salt Lake Office",
      "approvalGroupName": null,
      "costCenters": [{ "slot": 1, "typeKey": "dept", "value": "Sales" }],
      "amount": { "amount": "279.00", "currency": "USD" }
    },
    {
      "category": "EmployerTaxes",
      "side": "DEBIT",
      "transactionType": "Medicare (ER)",
      "transactionDetail": "Medicare (ER)",
      "glCode": "6200",
      "workLocationState": "UT",
      "workLocationName": "Salt Lake Office",
      "approvalGroupName": null,
      "costCenters": [{ "slot": 1, "typeKey": "dept", "value": "Sales" }],
      "amount": { "amount": "65.25", "currency": "USD" }
    },
    {
      "category": "AdditionalExpenses",
      "side": "DEBIT",
      "transactionType": "MEDICAL_INSURANCE",
      "transactionDetail": "Gold PPO",
      "glCode": null,
      "workLocationState": "UT",
      "workLocationName": "Salt Lake Office",
      "approvalGroupName": null,
      "costCenters": [{ "slot": 1, "typeKey": "dept", "value": "Sales" }],
      "amount": { "amount": "150.00", "currency": "USD" }
    },
    {
      "category": "Withholdings",
      "side": "CREDIT",
      "transactionType": "MEDICAL_INSURANCE",
      "transactionDetail": "Gold PPO",
      "glCode": "2100",
      "workLocationState": "UT",
      "workLocationName": "Salt Lake Office",
      "approvalGroupName": null,
      "costCenters": [{ "slot": 1, "typeKey": "dept", "value": "Sales" }],
      "amount": { "amount": "60.00", "currency": "USD" }
    },
    {
      "category": "Liabilities",
      "side": "CREDIT",
      "transactionType": "MEDICAL_INSURANCE",
      "transactionDetail": "",
      "glCode": "2110",
      "workLocationState": null,
      "workLocationName": null,
      "approvalGroupName": null,
      "costCenters": [],
      "amount": { "amount": "150.00", "currency": "USD" }
    },
    {
      "category": "PayrollFunding",
      "side": "CREDIT",
      "transactionType": "Cash funding",
      "transactionDetail": "",
      "glCode": "1000",
      "workLocationState": null,
      "workLocationName": null,
      "approvalGroupName": null,
      "costCenters": [],
      "amount": { "amount": "4784.25", "currency": "USD" }
    }
  ]
}

Each line has:

• A category, which says what kind of line it is. See below.
• A side, either DEBIT or CREDIT. The side is set by the category, and the amount is always positive.
• A transactionType and transactionDetail, which say exactly what the line is for within its category. This is what your GL codes are mapped to. The detail is an empty string when there's nothing more to say.
• A glCode: your company's GL code for the line, or null if no GL code has been mapped to it.
• The location, approval group, and cost centers the line belongs to. See How are lines split?.
• An amount.

Every journal balances: totalDebits always equals totalCredits. Lines that net to zero are left out. A funding that has no funded payments has no lines.

What are the line categories?

We may add categories in the future, so make sure your integration can handle a category it doesn't recognize.

Taxes and deductions that Everee withholds, funds, and remits for you (like income tax withheld from wages) don't appear as their own lines. They're already inside the gross wages and the cash funding.

Because of that, a funding's lines balance like this:

cash funding = wages + employer taxes + employer additional costs
               - paid outside Everee
               - withholdings that Everee doesn't remit
               - employer contributions that Everee doesn't remit (liabilities)
               - taxes that Everee doesn't fund (liabilities)

Employer contributions that Everee doesn't remit show up twice: as an AdditionalExpenses debit for the cost, and as a Liabilities credit for what you owe the plan.

Companies that file and remit their own taxes

If your company files and remits its own payroll taxes, Everee doesn't fund them with your payments. The cash funding is then net of both the taxes withheld from workers' wages and the employer taxes. The employer taxes are still EmployerTaxes debits, as for any company. To keep the journal balanced, the taxes Everee didn't fund show up as one Liabilities credit with the type Taxes for the whole funding, for what you owe the tax agencies.

This is worked out from each payment as it was funded, not from your company's current tax settings. If you change whether Everee funds your taxes, journals of earlier fundings stay the same and keep balancing.

How are GL codes chosen?

Your company maps GL codes to journal lines in Everee. A mapping applies to a category, and can narrow to a transactionType, and further to a transactionDetail. Every line gets the most specific mapping that matches it:

1. A mapping for its category, type, and detail.
2. Otherwise, a mapping for its category and type.
3. Otherwise, a mapping for its category alone.
4. Otherwise, the line's glCode is null.

In the example above, one mapping for GrossPay would code every wage line with the same GL code. A second mapping for GrossPay with the type FIELD_HOURS would give field hours their own GL code and leave all the other wages with the first one.

GL codes are resolved when you retrieve a journal, so a mapping you change applies to every journal you retrieve afterward, including journals of fundings in the past. If you've already posted a funding and later change a mapping, retrieve the journal again if you want the new codes.

How are lines split?

Wages keep the location, approval group, and cost centers they were coded to. Everything else is split across the cost centers of the wages on the same payment, in proportion to the wages. This is the same way the cost segments allocate employer taxes and other costs.

Let's say a payment has $3,000 in wages for the "Sales" department and $1,000 for "Ops", and $306 of employer Social Security tax. The GrossPay lines are one for each department, and the EmployerTaxes line is split into $229.50 for Sales (75%) and $76.50 for Ops (25%). Amounts are rounded to whole cents so the pieces always add up to the total.

The Liabilities, ExternalPayments, and PayrollFunding lines belong to the funding as a whole and don't have a location or cost centers.

Within a funding, lines that share a category, type, detail, GL code, location, and cost centers, from any number of payments, are combined into one line. A journal is therefore a summary of the funding, not a list of its payments. Use the Payment Data API if you need the payments.

A line's costCenters lists each cost center the line belongs to. Each entry has:

• The slot, 1, 2, or 3, which is the "Cost Center 1", "Cost Center 2", or "Cost Center 3" the type occupied when the wages were coded.
• The typeKey, the key of the cost center type the value was coded under. If you've since archived that cost center and put a new one in its slot, journals of earlier fundings still report their values under the original type's key.
• The value.

Choosing how lines are split

By default, lines are split by every cost field: the work location's state and name, the approval group, and all three cost centers. This is how the Payroll Journal report does it. Pass the group-by parameter, once for each field you want, to split by fewer fields:

GET https://api.everee.com/integration/v1/payroll-costs/journal/fundings/123456?group-by=work-location-state&group-by=cost-center-1

The values you can pass are work-location-state, work-location-name, approval-group-name, cost-center-1, cost-center-2, and cost-center-3. The fields you leave out are null or empty on every line, and the employer costs are split across only the fields you chose. A journal split by fewer fields has fewer lines, but it balances the same way.

If a payment's wages total zero or less, or none of its wages can be split, all of its employer costs go onto one line. That line has only the state of the worker's work location.

How does the journal compare to the cost segments?

Both come from the same payments, but they organize them differently, so you shouldn't expect their totals to match one for one:

Use the journal when you're keeping your books, and the cost segments when you're analyzing or invoicing your costs.