# Pay runs

URL: /systems/payroll · Id: `system:payroll`

> Pay runs keeps each employee’s pay record, prepares every run with withholding and deductions, and posts it to the Ledger.

Pay runs keeps each employee’s pay record, prepares every run with withholding and deductions, and posts it to the [Ledger](/systems/ledger). The [Payroll Specialist](/agents/people/payroll-specialist) approves each [Pay Run](/business/nouns/pay-run) within its [Limit](/business/nouns/limit), and a larger one waits for the founder.

## Summary
| Part | This System |
| --- | --- |
| Group | People |
| Status | Beta: it works, and its Verbs may still change |
| Shelf | Wakes: offered once its Event fires |

You can ask:

- “Run payroll this Friday”
- “Pay our contractor for March”
- “What does payroll cost each month?”
- “Send the year-end tax forms”

## What you get
| Part | This System |
| --- | --- |
| Starts | Opt-in: it wakes with the Product Templates that need it. |
| Wakes | On [`Agreement.signed`](/business/events/Agreement.signed) when you sign your first employee. |
| Built from | [Payroll](/systems/people/payroll), [Benefits](/systems/people/benefits), [Payment rails](/systems/finance/payments), [Workflows](/code/platform/workflows) |

## Nouns it owns
| Noun | Definition |
| --- | --- |
| [Worker](/business/nouns/worker) | A Worker is a Human or an Agent that fills a Role and acts on Tasks. |
| [Transaction](/business/nouns/transaction) | A Transaction is money moving on a payment rail, such as a charge, a payout, or a transfer, reconciled to Entries. |
| [Pay Run](/business/nouns/pay-run) | A Pay Run is one pay period’s payroll for a Company: each employee’s gross pay, withholding, deductions and net pay, approved and paid together. |

## Verbs
| Verb | Object | Approval | Event |
| --- | --- | --- | --- |
| [Human.remit](/business/nouns/human/remit) | [Human](/business/nouns/human) | Asks first; waits 1 business hour | [`Human.remitted`](/business/events/Human.remitted) |
| [PayRun.prepare](/business/nouns/pay-run/prepare) | [Pay Run](/business/nouns/pay-run) | None | [`PayRun.prepared`](/business/events/PayRun.prepared) |
| [PayRun.approve](/business/nouns/pay-run/approve) | [Pay Run](/business/nouns/pay-run) | Asks first; waits 1 business hour | [`PayRun.approved`](/business/events/PayRun.approved) |
| [PayRun.pay](/business/nouns/pay-run/pay) | [Pay Run](/business/nouns/pay-run) | Asks first; waits 1 business hour | [`PayRun.paid`](/business/events/PayRun.paid) |
| [PayRun.void](/business/nouns/pay-run/void) | [Pay Run](/business/nouns/pay-run) | None | [`PayRun.voided`](/business/events/PayRun.voided) |
| [Company.submit](/business/nouns/company/submit) | [Company](/business/nouns/company) | Asks first; waits 1 business hour | [`Company.submitted`](/business/events/Company.submitted) |

## Events
| Direction | Event | How |
| --- | --- | --- |
| Emits | [`Human.remitted`](/business/events/Human.remitted) | By [Human.remit](/business/nouns/human/remit) |
| Emits | [`PayRun.prepared`](/business/events/PayRun.prepared) | By [PayRun.prepare](/business/nouns/pay-run/prepare) |
| Emits | [`PayRun.approved`](/business/events/PayRun.approved) | By [PayRun.approve](/business/nouns/pay-run/approve) |
| Emits | [`PayRun.paid`](/business/events/PayRun.paid) | By [PayRun.pay](/business/nouns/pay-run/pay) |
| Emits | [`PayRun.voided`](/business/events/PayRun.voided) | By [PayRun.void](/business/nouns/pay-run/void) |
| Emits | [`Company.submitted`](/business/events/Company.submitted) | By [Company.submit](/business/nouns/company/submit) |
| Emits | [`Transaction.failed`](/business/nouns/transaction#transactionfailed) | Raised by the rail |
| Emits | [`Transaction.settled`](/business/nouns/transaction#transactionsettled) | Raised by the rail |

## States
The lifecycle of a [Pay Run](/business/nouns/pay-run):

| State | Meaning | Moves to |
| --- | --- | --- |
| `prepared` (first) | Every amount is computed and the run waits for approval; nothing is booked or paid. | `approved` by [PayRun.approve](/business/nouns/pay-run/approve); `voided` by [PayRun.void](/business/nouns/pay-run/void) |
| `approved` | The cost is booked and payment is scheduled to land on the pay date. | `paid` by [PayRun.pay](/business/nouns/pay-run/pay) |
| `paid` | Net pay reached each employee, and the payroll provider holds the taxes and deductions to remit. | None: it ends here. |
| `voided` | The run was set aside before approval; nothing was booked or paid, and the record stays. | None: it ends here. |

## Who operates it
| Part | This System |
| --- | --- |
| Accountable | [Payroll Specialist](/agents/people/payroll-specialist) |
| Team | [People Team](/agents/people) |
| Seat | A role agent holds it until a Human is seated. |
| Autonomy | `assist` |
| Also calls its Verbs | [Supply Manager](/agents/operations/supply-manager), [Finance Lead](/agents/finance/finance-lead), [Treasurer](/agents/finance/treasurer) |

## Approvals and limits
| Verb | Rule | Detail |
| --- | --- | --- |
| [Human.remit](/business/nouns/human/remit) | A person says yes first | Waits 1 business hour |
| [PayRun.approve](/business/nouns/pay-run/approve) | A person says yes first | Waits 1 business hour |
| [PayRun.pay](/business/nouns/pay-run/pay) | A person says yes first | Waits 1 business hour |
| [Company.submit](/business/nouns/company/submit) | A person says yes first | Waits 1 business hour |

## Processes that use it
| Process | How it uses it |
| --- | --- |
| [Supply](/workflows/processes/supply) | A step calls [Human.remit](/business/nouns/human/remit) |
| [Books](/workflows/processes/books) | A step calls [Company.submit](/business/nouns/company/submit) |
| [Billing](/workflows/processes/billing) | A Workflow writes [Transaction](/business/nouns/transaction) |
| [Payroll](/workflows/processes/payroll) | A step calls [Human.remit](/business/nouns/human/remit) |
| [Hiring](/workflows/processes/hiring) | A step calls [Human.remit](/business/nouns/human/remit) |
| [Delivery](/workflows/processes/delivery) | A Workflow writes [Transaction](/business/nouns/transaction) |
| [Expense approval](/workflows/processes/expense-approval) | A Workflow writes [Transaction](/business/nouns/transaction) |
| [Supplier payouts](/workflows/processes/supplier-payouts) | A step calls [Human.remit](/business/nouns/human/remit) |
| [Payables](/workflows/processes/payables) | A Workflow writes [Transaction](/business/nouns/transaction) |
| [Mail handling](/workflows/processes/mail-handling) | A Workflow writes [Transaction](/business/nouns/transaction) |
| [Staffing](/workflows/processes/staffing) | A step calls [Human.remit](/business/nouns/human/remit) |

## Rail underneath
| Noun | Stripe object | Source of truth |
| --- | --- | --- |
| [Transaction](/business/nouns/transaction) | **PaymentIntent** (`payment_intent`), when `kind` is `charge` | The source of truth is Stripe: db.sb mirrors it, written only from Stripe’s webhooks. |
| [Transaction](/business/nouns/transaction) | **Payout** (`payout`), when `kind` is `payout` | The source of truth is Stripe: db.sb mirrors it, written only from Stripe’s webhooks. |
| [Transaction](/business/nouns/transaction) | **Refund** (`refund`), when `kind` is `refund` | The source of truth is Stripe: db.sb mirrors it, written only from Stripe’s webhooks. |

| Capability | Runs on |
| --- | --- |
| [Payroll](/systems/people/payroll) | payruns.co |

## Views and dashboards
| View | Shows | Metrics |
| --- | --- | --- |
| Payroll | The next Pay Run and its cost, each paid run by Team, and every tax filing with its deadline. | [Pay accuracy](/agents/people#pay-accuracy) |

## Access
What each Access level may call here.

| Access level | May call |
| --- | --- |
| `owner` | Every Verb (15) |
| `admin` | All but 4 of 15: `Company.submit`, `Human.remit`, `PayRun.approve`, `PayRun.pay` |
| `member` | All but 4 of 15: `Company.submit`, `Human.remit`, `PayRun.approve`, `PayRun.pay` |
| `viewer` | Read only (6 of 15) |

## Import and export
None.

## Fees and pricing
The payroll provider bills each pay run under its Agreement once the run is paid, posted to the Ledger as a cost.

## Availability and limits
| Part | This System |
| --- | --- |
| Status | Beta: it works, and its Verbs may still change |

## Compliance notes
An officer signs employer returns or authorizes a reporting agent to; who is an employee and who a contractor stays the founder’s.

Controls it carries:

- [Action completion](/systems/trust-and-governance/controls/action-completion)

## Related Systems
- [Workforce](/systems/workforce)
- [Ledger](/systems/ledger)
- [Tax](/systems/tax)
- [Treasury](/systems/treasury): also holds [Transaction](/business/nouns/transaction)

## Example
A [Licensed-human marketplace](/products/templates/licensed-marketplace) with four employees in two states pays twice a month. Pay runs prepares each run with both states’ withholding and benefit deductions, and the Payroll Specialist approves it four days before payday. The Ledger shows the cost by [Team](/business/nouns/team) the same day.