API Reference
Start typing to search…

Get payroll expenses by pay period (or date range)

get https://api.everee.com/integration/v1/expenses/by-date-range
🚧

This endpoint is in Early Access

This is an Early Access endpoint and is not available for general use at this time. Breaking changes are possible until it reaches General Availability.

This endpoint allows you to retrieve total payroll expense data for a date range, typically a pay period.

This data includes the full-loaded cost of payroll for the period. It includes wages, employer payroll taxes, additional costs like benefit plan contributions and Workers' Comp insurance premiums, and so on.

You could use this data to populate financial reports per client, placement type, or any other way of organizing payroll costs, for each pay period. 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 "dimension" objects that match the Dimension IDs you specify on workers' wages, like timesheet hours and payable items . That means you'll receive a dimension object from this endpoint for each unique Dimension ID you've provided in the wage data.

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

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

📘

You control how expenses are allocated with Dimension IDs

We allocate expenses based on the Dimension IDs you provide alongside wage items. This lets you control how expenses are allocated: the more Dimension IDs you specify, the more dimensions of payroll expense data you'll receive from this endpoint. Check out the Guide to Payroll Expenses to learn more.

Typically, you'll retrieve data from the endpoint once per pay period 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 "processed" payroll data appears in this endpoint. Payroll data is processed 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 dimensions?

Hourly wages

Hourly wages are allocated to dimensions by their dimensions property 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 dimensions by their dimensions property specified via the Payables API.

Paid time off

Wages for PTO, sick time, and other leave types can't be allocated to custom dimensions at this time. All of these wages appear in the unallocated dimension (see below).

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

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

Let's say you report payroll expenses based on placement type, so you use a placementType dimension 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 placement types in one week: Shipper, Forklift Operator, and General Warehouse.

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

{
  "shiftStartAt": "1758384961",
  "shiftEndAt": "1758410161",    // 7 hours of work
  "hourlyPayRate": { "amount": "26.00", "currency": "USD" },
  "dimensions": { "placementType": "shipper_xyz" },
  // ...
}

Here, Jane's wages for this 7-hour shift working as a Shipper ($182.00 in gross wages) would be allocated to the placementType dimension called shipper_xyz.

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

[
  {
    "dimension": { "placementType": "shipper_xyz" },
    "totalWageAmount": { "amount": "10120.50", "currency": "USD" },
    // ...
  },
  {
    "dimension": { "placementType": "forklift_operator_xyz" },
    "totalWageAmount": { "amount": "9001.89", "currency": "USD" },
    // ...
  },
  {
    "dimension": { "placementType": "warehouse_general_xyz" },
    "totalWageAmount": { "amount": "10444.00", "currency": "USD" },
    // ...
  }
]

Note that the dimensions in the example above include payroll expenses for all workers paid in the week, not just for Jane's payroll expense.

In this example, Jane's wages for the Shipper shift above are allocated to the placementType dimension shipper_xyz, along with all other wages for all workers who worked Shipper shifts during that week too.

How are payroll taxes and other costs allocated to dimensions?

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

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

📘

Employees working in multiple states within a pay period

When employees work in multiple states in a single pay period, and you're allocating their wages to multiple dimensions, it's possible for SUTA and other state-level employer taxes from all states to be split across all the dimensions their wages are allocated to. We can't isolate payroll taxes from different states into different dimensions automatically.

If this scenario is common for your business, you should take this behavior into account when choosing the dimension types you'll use for payroll expenses.

How does the "unallocated dimension" work?

You'll typically want to make sure as much of your payroll expense as possible is correctly allocated to the right dimensions. 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 dimension at all. When this happens, we place these unallocated payroll expenses in the unallocated dimension.

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 dimension 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 placement type, 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 dimension. You can place this dimension's numbers into a "General & Administrative" or similar cost center, or spread it out across other cost centers—whatever makes sense for your accounting strategy.

This dimension is returned from this endpoint with an empty dimension property:

[
  {
    "dimension": {},   // empty!
    "totalWageAmount": { "amount": "1000.00", "currency": "USD" },
    // ...
  }
]

The unallocated dimension is otherwise a regular dimension object alongside the rest. It just doesn't have a custom dimension identifier. See the example response data on the right for a populated sample of the unallocated dimension.

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


Language
Credentials
Header