Add items to a payroll run

post

https://api.everee.com/integration/v1/payroll-runs/{id}/items

Add items of pay to an OPEN, CALCULATING, READY or BLOCKED run, or update items it already has, matched by externalId. Every item is a pre-calculated amount: send what you've already calculated, under a pay code. Everee sets each item's type to PAYROLL_RUN_ITEM, and dates it to the last day of the run's pay period. See Earning date. Each worker's items are combined into one payment in the run. A READY or BLOCKED run goes back to OPEN, so calculate it again.

Send up to 1,000 items at a time. Every item is checked before any is saved: if any can't be accepted, nothing is saved and the 400 response lists every failing item. See Sending many items.

To correct an item whose payment has already been paid, send correction-authorized=true. See Adding, updating and correcting items for what happens to an externalId Everee has seen before.

Path Params

string

required

The payroll run's ID. It's numeric: any other value returns 400.

Query Params

correction-authorized

boolean

Defaults to false

Set to true to correct an item that's already been paid. Without it, an item whose payment is already paid is rejected.

Body Params

items

array of objects

required

length between 1 and 1000

items*

An item of pay to add to a payroll run. Every item is a pre-calculated amount: you calculate amount before sending it. Everee sets each item's type to PAYROLL_RUN_ITEM, and dates it to the last day of the run's pay period, or to the worker's end date if their employment ended earlier.

externalId

string

required

Your unique ID for the item. Sending an externalId the run already has updates that item. See Adding, updating and correcting items.

workerId

string

Everee's ID for the worker to pay. Send workerId or externalWorkerId.

externalWorkerId

string

Your ID for the worker to pay. Send workerId or externalWorkerId.

label

string

required

A description of the item. It can appear on worker-facing documents.

amount

object

required

The amount, which you calculate. Not negative.

payCode

string

required

The item's pay code. See Pay codes and gross pay basics. To pay out leave, use the leave type's pay code, which starts with TIME_OFF_TYPE_.

unitRate

object

The rate the amount was earned at, if any.

unitCount

number

The number of units, such as hours, if any. Required, as hours, for a leave payout.

workLocationId

number

The ID of the work location the item is assigned to.

ttocCode

number

The Treasury Tipped Occupation Code, if any.

workersComp

object

The workers' comp class for this item, given directly instead of from the company's workers' comp classes. Everee calculates the premium from these values.

costCenters

array of objects

length ≤ 3

Up to three cost centers for the item's expense. Each type must be the key of an active cost center. Workers' default cost centers aren't applied to items.

costCenters

Responses

Language

Credentials

Header

Loading…

Response

Choose an example:

application/json

201The items created or updated, as the run now has them.

400One or more items can't be accepted, and nothing was saved: errors lists every one. Or the request has more than 1,000 items, the ID isn't numeric, or the company isn't set up for Payroll Infrastructure, which return the usual error body. See Errors in bulk requests.

404No payroll run with that ID exists for the company.

409The run isn't OPEN, CALCULATING, READY or BLOCKED.

422The body is invalid, for example a required field is missing or an amount is negative.