---
updatedAt: 2026-11-09T22:38:02.000Z
agentTools:
  projectIndex: https://developer.everee.com/llms.txt
---

# Running Payroll

Add pay to a payroll run, calculate it, fix what blocks it, approve it, and follow the money until workers are paid.

In Payroll Infrastructure there is no admin portal and no admin users. You run payroll through the API, with the [Payroll Run API](https://developer.everee.com/reference/payroll-run-api-guide).

A **payroll run** is one payroll for a company. You calculate each worker's gross pay and add it to the run as items, under pay codes. Everee calculates taxes, deductions and net pay, and tells you if anything must be fixed first. You approve the run, and Everee funds it from the company's funding account and pays the workers.

Payroll runs are the only way to pay workers in Payroll Infrastructure. Creating payables or timesheet hours directly, or approving payments outside a run, returns `400`.

## Before the first run

* **The company is approved.** Until Everee approves the company, a calculated run is `BLOCKED` with `COMPANY_NOT_APPROVED`. See [Submitting for review](https://developer.everee.com/docs/submitting-for-review).
* **The company is live.** Everee makes it live once its payroll history is imported and its setup is finished. `goLive` on the onboarding status, and the `company-onboarding.went-live` event, tell you when. See [Payroll history and going live](https://developer.everee.com/docs/payroll-history-and-going-live).
* **The funding bank account is connected.** Everee debits it to fund each run. See [Funding payroll](https://developer.everee.com/docs/funding-payroll).
* **The company has a payroll calendar.** Each pay period on it gets a regular payroll run. See the [Payroll Calendar API](https://developer.everee.com/reference/payroll-calendar-api-guide).
* **Workers are set up**, with what Everee needs to pay them. See [Managing workers](https://developer.everee.com/docs/managing-workers). The [Requirements API](https://developer.everee.com/reference/requirements-api-guide) lists anything that's still missing, so you can fix it before payroll day.
* **A webhook endpoint is subscribed.** The run moves on in the background, and [webhook events](#webhook-events) tell you when.

## Step by step

### 1. Open the run

When the payroll calendar creates a pay period, Everee creates its run, `UNOPENED`, and sends `payroll-run.created`. You can also [list the company's runs](https://developer.everee.com/reference/list-payroll-runs). Open the run with the date workers should be paid:

```http
POST /integration/v1/payroll-runs/4821/open
{ "targetPayDate": "2026-11-20" }
```

The pay date must be a banking day, and no earlier than the company can pay, which depends on its funding type. To offer the dates it can take, [list the run's pay dates](https://developer.everee.com/reference/list-payroll-run-pay-dates) when you show the choice. The run moves to `OPEN`, and its `approvalDeadline` is set: approve by then for workers to be paid on the pay date. Its `fundingDate` is the day the run's funding is debited from the company's funding account. The pay dates list gives both for each date, in `options`, so you can show them before you open the run.

For an extra payroll, such as a bonus run, [create an off-cycle run](https://developer.everee.com/reference/create-off-cycle-payroll-run) instead. It starts `OPEN`. See [Corrections and off-cycle runs](https://developer.everee.com/docs/corrections-and-off-cycle-runs).

### 2. Add pay

[Add items](https://developer.everee.com/reference/add-payroll-run-items), each with your `externalId`, the worker, a pay code and an amount you've calculated. Everee dates every item to the last day of the run's pay period, so you don't send a date. See [Earning date](https://developer.everee.com/reference/payroll-run-api-guide#earning-date).

```http
POST /integration/v1/payroll-runs/4821/items
{
  "items": [
    {
      "externalId": "shift-88213",
      "externalWorkerId": "emp-1042",
      "label": "Regular hours, Nov 3",
      "payCode": "REGULAR_HOURLY",
      "amount": { "amount": "200.00", "currency": "USD" },
      "unitCount": 8,
      "unitRate": { "amount": "25.00", "currency": "USD" }
    }
  ]
}
```

Send up to 1,000 items per request, and as many requests as you need. Everee checks every item before saving any: if some can't be accepted, nothing is saved and the response lists every failing item, so you can fix them all and send the request again. See [Sending many items](https://developer.everee.com/reference/payroll-run-api-guide#sending-many-items).

Send items as often as you like until you approve. Sending an `externalId` again updates the item, and [removing an item](https://developer.everee.com/reference/remove-payroll-run-item) takes it off. Each worker's items are combined into one payment in the run. See [Pay codes and gross pay basics](https://developer.everee.com/docs/gross-pay-basics) for what to send, including hours, overtime and reimbursements.

### 3. Calculate

[Calculate the run](https://developer.everee.com/reference/calculate-payroll-run). It moves to `CALCULATING`, and Everee sends `payroll-run.status-changed` when it finishes:

* **`READY`**: nothing blocks it. Review it and approve it.
* **`BLOCKED`**: something must be fixed first. See the next step.
* **`OPEN`**: items were added while it calculated. Calculate it again.

Any change after the calculation (an item added, updated or removed, or a payment excluded) sends the run back to `OPEN`. Calculate it again before approving.

### 4. Fix what blocks it

[List the run's blockers](https://developer.everee.com/reference/list-payroll-run-blockers). Each one says what it's about and how to fix it, in `resolutionInstructions`. For example:

```json
{
  "requirementId": "5530",
  "subjectType": "WORKER",
  "subjectId": "emp-1042",
  "workerId": "6f1c2a9e-4b7d-4a51-9a40-2f6c8d1e7b33",
  "externalWorkerId": "emp-1042",
  "sourceDomain": "WORKER_PROFILE",
  "type": "INVALID_BANK_ACCOUNT",
  "status": "OPEN",
  "resolutionInstructions": "Update the worker's direct deposit bank account with a valid routing and account number."
}
```

When the last blocker is resolved, the run goes back to `OPEN`. Calculate it again. If a worker can't be fixed in time, [exclude their payment](https://developer.everee.com/reference/exclude-payroll-run-payment) so the rest of the run can be paid. The [requirement types](https://developer.everee.com/reference/requirements-api-guide#requirement-types) list every blocker and its fix.

### 5. Review

[List the run's payments](https://developer.everee.com/reference/list-payroll-run-payments) to see each worker's wages, taxes, deductions, employer costs and net pay before you approve.

### 6. Approve

[Approve the run](https://developer.everee.com/reference/approve-payroll-run) before its `approvalDeadline`. It moves to `APPROVING`, then `APPROVED`. If something was wrong, you can [reopen it](https://developer.everee.com/reference/reopen-payroll-run) until its `reopenDeadline`: it goes back to `OPEN`, so you can change it and approve it again.

### 7. Follow the money

Every list in the API, such as a run's items or payments, is cursor-paginated: send each page's `nextCursor` as `after` until `hasNextPage` is `false`. See [Listing and paging](https://developer.everee.com/reference/payroll-run-api-guide#listing-and-paging).

When money starts moving, the run moves to `PROCESSING`, and to `PAID` once every payout has gone out.

* **Funding.** Everee debits the company's funding account. [Retrieve the run's funding](https://developer.everee.com/reference/retrieve-payroll-run-funding) to see the amount and date, and its status. If it needs action, see [Funding payroll](https://developer.everee.com/docs/funding-payroll).
* **Payouts.** Each worker's net pay goes out as one or more [net payouts](https://developer.everee.com/reference/net-payouts-api-guide), by direct deposit. A payout that's returned can be retried. See [Returned Deposits and Retries](https://developer.everee.com/docs/returned-deposits-and-retries).
* **Done.** The run is `PAID` when every payout has gone out, or `PARTIALLY_PAID` when some didn't reach the worker. A direct deposit counts as delivered two banking days after it's sent, if it hasn't come back. While the run waits on its direct deposits, its `expectedPaidDate` is the day Everee expects to mark it `PAID` or `PARTIALLY_PAID`.

For accounting, read the run's payments, or use the [payroll journal](https://developer.everee.com/reference/payroll-journal-guide) and [payment data](https://developer.everee.com/reference/payment-data-api-guide). See [Reconciling payroll and posting to your GL](https://developer.everee.com/docs/reconciling-payroll-and-gl).

## Webhook events

Subscribe a [webhook endpoint](https://developer.everee.com/reference/webhook-endpoints-api-guide) to follow runs without polling:

| Event                                                          | Use it to                                                                                      |
| :------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- |
| `payroll-run.created`                                          | Find each new run to open                                                                      |
| `payroll-run.status-changed`                                   | Know when a calculation finishes, an approval is processed, a run is blocked, or a run is paid |
| `payroll-run.funded`, `payroll-run.funding-failed`             | Follow the run's funding                                                                       |
| `requirement.created`, `requirement.resolved`                  | Prompt someone to fix a requirement, and know when it's fixed                                  |
| `net-payout.paid`, `net-payout.returned`, `net-payout.retried` | Tell workers they've been paid, and follow returned deposits                                   |

Each event carries the same object the API returns. See [Payroll Run Events](https://developer.everee.com/docs/payroll-run-events).

## Next

* [Funding payroll](https://developer.everee.com/docs/funding-payroll): the funding account, funding that needs your action, and returned debits.
* [Corrections and off-cycle runs](https://developer.everee.com/docs/corrections-and-off-cycle-runs): extra payrolls, changing or reopening a run, and correcting pay that's been paid.
* [After payroll](https://developer.everee.com/docs/after-payroll): payouts, what to show workers, and reconciliation.

The [Guide to the Payroll Run API](https://developer.everee.com/reference/payroll-run-api-guide) has every status, rule and error.