📈 Guide to the Payroll Cost API

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

This guide covers the cost segments, which organize payroll costs by cost center. You retrieve them by period or by cost centers, under /integration/v1/payroll-costs/segments. The Payroll Cost API also includes the payroll journal, which gives each funding as balanced debit and credit lines with your GL codes, ready to post to your general ledger. See the Guide to the payroll journal for that.

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 cost data is allocated into 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 a data 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 costs split into 30 different cost segments, one for each client.

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

Typically, you'll retrieve data 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 payments that have been paid appear in this endpoint: payments that have been submitted for deposit to workers, or deposited. A payment that is approved but still waiting to be submitted for deposit (for example, scheduled for a later date) appears once it has been submitted.

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. For any cost center type you don't specify on a shift or time card, the worker's default for that type is used, if they have one. See the Guide to cost centers for how to set worker defaults.

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

Wages generated automatically for PTO, sick time, and other leave types can't be coded to cost centers individually. They're allocated using the worker's default cost centers, if the worker has any. Leave wages for workers without defaults appear in the unallocated cost segment (see below).

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

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

Let's say you report payroll costs based on job type, so you use a jobType cost center type to organize costs. You'll retrieve payroll cost 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:

{
  "shiftStartEpochSeconds": 1758384961,
  "shiftEndEpochSeconds": 1758410161,    // 7 hours of work
  "effectiveHourlyPayRate": { "amount": "26.00", "currency": "USD" },
  "costCenters": [
    {
      "type": "jobType",
      "value": "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 cost, for her shifts in all three job types during that week, would be split across three different cost 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 cost segments in the example above include payroll costs for all workers paid in the week, not just for Jane's payroll cost, 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 costs, 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.

What are additional costs?

Employer-level, non-tax costs – benefit plan contributions, Workers' Comp insurance premiums, and similar – are reported as additional costs. Each cost segment reports them in totalEmployerAdditionalCostAmount (the total) and employerAdditionalCostAmounts (the breakdown by type, including Workers' Comp state and rate details).

How do net payouts work?

Each cost segment includes a netPayouts array listing the net payouts to workers (their take-home pay) for payments with wages in that cost center. Each entry is one worker-facing payout – a direct deposit, pay card load, check, and so on.

When a payment's wages are allocated to more than one cost center, each payout is apportioned across those cost centers by each one's share of the payment's earnings, exactly like employer taxes and other costs (see above). The same payout then appears in every cost center segment it touches, with the same netPayoutId and a different amount. Amounts are rounded to whole cents in a way that guarantees a payout's portions always add up to its full amount, so you can safely add up segments across a pay period.

{
  "costCenterTypeKey": "jobType",
  "costCenterValue": "packer",
  "totalNetPayAmount": { "amount": "1435.57", "currency": "USD" },
  "netPayouts": [
    { "payDate": "2025-09-26", "netPayoutId": "48213377", "amount": { "amount": "861.34", "currency": "USD" } },
    { "payDate": "2025-09-26", "netPayoutId": "48213378", "amount": { "amount": "574.23", "currency": "USD" } }
  ]
}

How does the "unallocated cost segment" work?

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

However, it's possible for certain payroll costs to not be allocated to a cost center at all. When this happens, we place these unallocated payroll costs in the unallocated cost 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 for workers without default cost centers

These unallocated payroll costs still need to be accounted for, so they're included in the unallocated cost 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 cost 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 cost segment is otherwise a regular cost 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 cost segment.

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