📈 Guide to the Payroll Expenses API

The Payroll Expenses API lets you retrieve full-detail payroll ledger data, on-demand and organized into segments of your choosing.

You could use this data to populate financial reports per client, job type, or any other way of organizing payroll costs, for each pay period, client, job, or shift. You could also use this data to populate invoices if you need to include fully-loaded payroll costs as line items on your invoices.

This payroll expense data is allocated into expense segments that match the cost centers you specify on workers' wages (via the costCenters properties), like timesheet hours and payable items . That means you'll receive an expense segment from this endpoint for each unique cost center you've provided in the wage data.

Let's say you allocate wages to 30 different clients in a pay period, using 30 different cost centers to represent those clients in employees' wage data. In that case, this endpoint will return your total payroll expenses split into 30 different expense segments, one for each client.

You'll also get one more expense segment for "unallocated" payroll expenses that can't be allocated to a cost center. See below for details on that.

Typically, you'll retrieve data from a Payroll Expenses endpoint once per pay period, after payroll has been finalized, to obtain a complete picture of payroll expenses for the period. This would usually be aligned to the regular schedule used for invoicing, expense reporting, and so on.

Note that only "finalized" payroll data appears in this endpoint. Payroll data is finalized when it's approved in Everee for deposit to workers. This happens immediately when payments are approved in the Everee admin portal, including daily, weekly, scheduled on a prior date, off-cycle, and so on.

How are wages allocated to cost centers?

Hourly wages

Hourly wages are allocated to cost centers by their costCenters properties specified via the Timesheets API.

Non-hourly payable items

All payable items (bonuses, stipends, contractor pay, and so on – not hourly wages) are allocated to cost centers by their costCenters properties specified via the Payables API.

Paid time off

Any wages generated automatically for PTO, sick time, and other leave types can't be allocated to custom cost centers at this time. All of these wages appear in the unallocated expense segment (see below).

Can a worker's wages be allocated to multiple cost centers in a single pay period?

Yes! Payroll expenses are allocated to cost centers at the wage level, not at the worker level.

Let's say you report payroll expenses based on job type, so you use a jobType cost center type to organize costs. You'll retrieve payroll expense data every week to run a profit report per weekly pay period.

Jane Appleseed, a candidate placed with a client, will work shifts on three different job types in one week: Packer, Forklift Operator, and General Warehouse.

In this scenario, you could record Jane's shift for these hours worked as a packer:

{
  "shiftStartAt": "1758384961",
  "shiftEndAt": "1758410161",    // 7 hours of work
  "hourlyPayRate": { "amount": "26.00", "currency": "USD" },
  "costCenters": [
    {
      "costCenterTypeKey": "jobType",
      "costCenterValue": "packer"
    }
  ],
  // ...
}

Here, Jane's wages for this 7-hour shift working as a packer ($182.00 in gross wages) would be allocated to the cost center type jobType with value packer.

Jane's total payroll expense, for her shifts in all three job types during that week, would be split across three different expense segments from this API endpoint, one for each job type:

[
  {
    "costCenterTypeKey": "jobType",
    "costCenterValue": "packer",
    "totalWageAmount": { "amount": "10120.50", "currency": "USD" },
    // ...
  },
  {
    "costCenterTypeKey": "jobType",
    "costCenterValue": "forklift",
    "totalWageAmount": { "amount": "9001.89", "currency": "USD" },
    // ...
  },
  {
    "costCenterTypeKey": "jobType",
    "costCenterValue": "warehouse_general",
    "totalWageAmount": { "amount": "10444.00", "currency": "USD" },
    // ...
  }
]

Note that the expense segments in the example above include payroll expenses for all workers paid in the week, not just for Jane's payroll expense, since there were many workers earning wages under each of those cost centers.

In this example, Jane's wages for the "packer" shift above are allocated to the cost center type jobType = packer, along with all other wages for all workers who worked "packer" shifts during that week too.

How are payroll taxes and other costs allocated to cost centers?

Employer payroll taxes, benefit plan contribution expenses, Workers' Comp insurance premiums, and all other non-wage costs are allocated to cost centers using the same allocation as the wages that originated them.

That means if a worker's wages were allocated to two different cost centers in a pay period, all additional payroll costs will be split across those cost centers according to the proportion of wages earned in each of those two cost centers.

How does the "unallocated expense segment" work?

You'll typically want to make sure as much of your payroll expense as possible is correctly allocated to the right cost centers. This gives you the most accurate breakdown of your payroll expenses when reporting later.

However, it's possible for certain payroll expenses to not be allocated to a cost center at all. When this happens, we place these unallocated payroll expenses in the unallocated expense segment.

There are a few reasons this can happen, including:

1. Special payouts, like a one-time disbursement of funds to a worker due to a unique contractual arrangement
2. Hourly wages for an unusual type of work that isn't mapped to a particular cost center in your system because it only happens rarely
3. Paying out certain wage types that can't be invoiced to a specific client or allocated to a specific cost center, like state-mandated sick time or FMLA wages

These unallocated payroll expenses still need to be accounted for, so they're included in the unallocated expense segment. You can place this segment's numbers into a "General & Administrative" or similar cost center in your own accounting system, or spread it out across other cost centers—whatever makes sense for your accounting strategy.

This expense segment is returned from this endpoint with null costCenterTypeKey and costCenterValue properties:

[
  {
    "costCenterTypeKey": null,   // null!
    "costCenterValue": null,   // null!
    "totalWageAmount": { "amount": "1000.00", "currency": "USD" },
    // ...
  }
]

The unallocated expense segment is otherwise a regular expense segment alongside the rest. It just doesn't have a cost center attached. See the example response data on the right for a populated sample of the unallocated expense segment.

Don't ignore the unallocated expense segment! If you skip or fail to handle the data in the unallocated expense segment, you won't be working with a full picture of payroll expenses, which will cause gaps and errors in reports.