Guide to the Payroll Run API

A payroll run is one payroll for a company: the pay for one pay period, or an extra payroll on a date you choose. The Payroll Run API is how you run payroll in Payroll Infrastructure. You add each worker's pay to a run as items, have Everee calculate it, fix anything that blocks it, and approve it. Everee then funds the run from the company's funding account and pays the workers.

For the end-to-end walkthrough, see Running payroll. This guide is the reference for the run itself.

📘

Payroll Infrastructure only

Payroll runs exist only for Payroll Infrastructure companies. Every endpoint that changes a run returns 400 for a company whose payroll is run in the Everee admin portal. For a Payroll Infrastructure company, payroll runs are the only way to pay workers: the Payables and Timesheets endpoints that create pay return 400, and payments can't be approved outside a run.

Call these endpoints with the company's API key. See Authentication and API tokens.

Two related APIs complete the picture. The Net Payouts API lists what each worker was paid and how. The Requirements API lists what's keeping the company's payroll from processing, across every run.

Listing and paging

Every list in this API, and in the Net Payouts and Requirements APIs, uses cursor pagination. Send limit for the page size, from 1 to 1,000 (100 if you leave it out). Each page has hasNextPage, and when there's a next page, nextCursor: send it as after to get that page. Keep going until hasNextPage is false.

Each list has a fixed order, so page, size and sort aren't accepted:

Items added while you page through a run land after the ones you've read, so a pass through the list never skips or repeats an item. Pages don't carry totals: the run itself has itemCount, paymentCount and totalNetPay.

Regular and off-cycle runs

Regular runs come from the company's payroll calendar. When the calendar creates a pay period, Everee creates its run with status UNOPENED and sends payroll-run.created. Open it with a targetPayDate to start adding pay.

Off-cycle runs are extra payrolls, such as a bonus run or a final paycheck. Create one with a targetPayDate. It starts OPEN, on a pay period of its own, and Everee sends payroll-run.created.

Pay dates and deadlines

targetPayDate must be a banking day, and no earlier than the first date the company can pay. That date depends on the company's funding type, which for an off-cycle run is its funding type for ad hoc payments. A pay date that's too early returns 400 naming the earliest date allowed.

Each run has up to three deadlines. Read them from the run rather than working them out yourself:

All timestamps are UTC.

A run also has its totals: itemCount, paymentCount (leaving out excluded payments), and totalNetPay, those payments' net pay as last calculated. totalNetPay is only final once the run is READY.

Payroll run statuses

A run moves forward like this:

1. UNOPENED → OPEN when you open it. An off-cycle run starts at OPEN.
2. OPEN → CALCULATING when you calculate it.
3. CALCULATING → READY when nothing blocks it, BLOCKED when something does, or back to OPEN when items were added during the calculation and still need calculating.
4. READY → APPROVING → APPROVED when you approve it.
5. APPROVED → PROCESSING when money starts moving, then PAID or PARTIALLY_PAID. A direct deposit counts as delivered two banking days after it's sent, if it hasn't come back, so a run can stay PROCESSING after every payout shows PAID.

And back:

• READY or BLOCKED → OPEN when you add, update or remove an item, or exclude a payment.
• BLOCKED → OPEN when its last blocker is resolved. Calculate it again.
• APPROVED → OPEN when you reopen it. Its payments are unapproved.
• APPROVED → OPEN when Everee can't approve its payments on their funding date. Calculate and approve it again.
• PROCESSING_BLOCKED → PROCESSING when you retry its funding, or OPEN when processingBlockedDeadline passes. Approve it again for a later pay date.
• PROCESSING → OPEN when the company's bank returns the run's funding debit before workers were paid. The run gets a FUNDING_FAILED blocker. Make sure the account has the money, then calculate and approve it again.

Every change sends a payroll-run.status-changed webhook event with the run and its previous status. A request that a run's status doesn't allow returns 409, with the status in errorMessage.

Adding, updating and correcting items

An item is one amount of pay for one worker: hours at a rate, a bonus, a reimbursement. You calculate the amount and send it under a pay code. See Pay codes and gross pay basics. Send each item with your externalId, the worker, a label, a payCode and an amount, and unitCount and unitRate when the pay is per unit, such as hours. Everee sets the rest:

They're returned on each item, and ignored if you send them.

Each item has your externalId. What happens depends on whether Everee has seen it before:

The response is the items you sent, as the run now has them. A worker's payment in the run combines all of that worker's items, so one worker never has two payments in one run.

Earning date

Every item in a run is earned on the last day of the run's pay period, its periodEnd. For a worker whose employment ended before periodEnd, it's their end date instead, so their final pay can still be added. earningTimestamp is the start of that day in the worker's time zone.

An item that moves to another run, or corrects a paid item in a later run, takes the earning date of the run it's added to.

Sending many items

A request can add up to 1,000 items. To add more, send several requests: a run with a few thousand items takes a few calls.

Everee checks every item before saving any. If any item can't be accepted, nothing is saved, and the 400 response lists every failing item, with its position, the IDs you sent, an errorCode, and the field at fault. See Errors in bulk requests. Fix them and send the whole request again: items are matched by externalId, so sending the same items twice is safe.

When an item updates one the run already has, it's checked as the update leaves it: a field you leave out, such as a leave payout's unitCount, keeps its value.

Remove an item takes its amount off the worker's payment, and deletes the payment when it was the last item. Exclude a payment leaves a worker out of the run entirely: the payment stays listed with status EXCLUDED and the reason you gave, and its items are deleted. A payment can be excluded until it's approved.

Items carry their worker as workerId and externalWorkerId. externalWorkerId is null for a worker you created without one. Filter items and payments by either, with worker-id and external-worker-id.

earningTimestamp is Unix epoch seconds, and workLocationId is a number, as in the payables API. Every other ID in this API is a string, and every other time is an ISO 8601 timestamp.

Calculating

Calculate a payroll run queues the run, which moves to CALCULATING. Calculation happens in the background: wait for the payroll-run.status-changed event rather than polling, and read the run when it arrives.

While Everee calculates, it also checks the run for anything that would stop it being paid. For a company that funds payroll before it's paid out, that includes the company's funding account balance: a run the balance can't cover is BLOCKED with INSUFFICIENT_FUNDS, and the balance is checked again on each calculation.

Blockers

List a payroll run's blockers to see why a run is BLOCKED. Each blocker says what it's about (subjectType and subjectId), its type, and resolutionInstructions for fixing it. Blockers are returned in a fixed order, by source domain, then type, then subject, and can't be sorted.

Most blockers come from a requirement, and share its fields. A blocker that comes from a payment's own error, or from the company not being approved yet, has no requirementId. The requirement types say what each one means.

When a run's last blocker is resolved, the run goes back to OPEN. Calculate it again to get to READY.

Payments

List a payroll run's payments once the run is calculated. Each payment is one worker's pay, with everything it was calculated to:

• taxableWages and nonTaxablePay, by pay code, and their totals
• employerTaxes and employeeTaxWithholdings, with the wages each was calculated on
• employeeDeductions, including garnishments
• employerAdditionalCosts: employer contributions, and workers' comp premiums with their class and rate
• totalNetPay, and the netPayouts it's paid out as

Payment statuses

Approving and reopening

Approve a READY run before its approvalDeadline. The run moves to APPROVING, then APPROVED. If its payments are funded on a later day, Everee approves them on that day.

Approval is refused with 409 while a funding debit returned after workers were paid hasn't been repaid. The company then has an open FUNDING_FAILED requirement. Contact Everee Customer Success to repay it.

Until reopenDeadline, you can reopen an APPROVED run. Its payments are unapproved and it goes back to OPEN, so you can change it and approve it again.

Funding

Once a run is approved, retrieve its funding to follow the money from the company's funding account. Before approval it returns 404.

A funding that needs action puts the run in PROCESSING_BLOCKED. Follow resolutionInstructions: for example, move money into the account, or send the wire. Then retry the funding before the run's processingBlockedDeadline. The run goes back to PROCESSING: a funding held for insufficient funds is sent when the balance covers it, and otherwise goes back to review. If the deadline passes first, the run goes back to OPEN, to approve again for a later pay date.

A retry's funding names the funding it replaced in previousFundingId. Everee sends payroll-run.funded when a funding is collected and payroll-run.funding-failed when one fails, each with the funding.

Webhook events

Each event's object is the same as the API returns. See Payroll Run Events for the payloads, and the net payout and requirement events.

Errors

The error body is described in Requests and responses.