# Pay Run

URL: /business/nouns/pay-run · Id: `noun: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.

A Pay Run is one pay period’s payroll for a [Company](/business/nouns/company): each employee’s gross pay, withholding, deductions and net pay, approved and paid together.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `company` | [Company](/business/nouns/company) | Yes | The employer of record for everyone it pays. |
| `periodStart` | `date` | Yes | The first day of the pay period. |
| `periodEnd` | `date` | Yes | The last day of the pay period. |
| `payDate` | `date` | Yes | The day net pay reaches each employee’s bank. |
| `kind` | `string` | Yes | A `regular` run on the pay schedule, or an `offCycle` run for a bonus, a correction or final pay. |
| `humans` | list of [Human](/business/nouns/human) | No | The employees it pays. |
| `gross` | `money` | No | Pay before withholding and deductions, for everyone in the run. |
| `withheld` | `money` | No | Income and payroll taxes withheld from employees’ pay. |
| `deductions` | `money` | No | Benefit and retirement deductions the employees elected. |
| `employerTax` | `money` | No | Payroll taxes the Company owes on top of gross pay. |
| `net` | `money` | No | What reaches the employees’ banks: gross less withholding and deductions. |
| `status` | `string` | Yes | Where the Pay Run stands; only an `approved` run is paid. |

## Object
```json
{
  "$id": "https://api.sb/kilnbakery.com/pay-runs/pay_run_1",
  "$type": "PayRun",
  "company": "company_1",
  "periodStart": "2026-10-22",
  "periodEnd": "2026-10-22",
  "payDate": "2026-10-22",
  "kind": "regular",
  "humans": [
    "human_1"
  ],
  "gross": {
    "amount": 9,
    "currency": "USD"
  },
  "withheld": {
    "amount": 9,
    "currency": "USD"
  },
  "deductions": {
    "amount": 9,
    "currency": "USD"
  },
  "employerTax": {
    "amount": 9,
    "currency": "USD"
  },
  "net": {
    "amount": 9,
    "currency": "USD"
  },
  "status": "prepared"
}
```

## Relationships
- <a id="rel-paid-by"></a>A Pay Run **is paid by** one [Company](/business/nouns/company): a Pay Run is paid by one [Company](/business/nouns/company), the employer of record for everyone in it. `paidBy`, inverse [`payRuns`](/business/nouns/company#rel-pay-runs).
- <a id="rel-pays"></a>A Pay Run **pays** many [Humans](/business/nouns/human): a Pay Run pays the [Humans](/business/nouns/human) the [Company](/business/nouns/company) employs; each employee appears in one run per pay period. `pays`, inverse [`paidIn`](/business/nouns/human#rel-paid-in).

## Lifecycle

| 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. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [PayRun.approve](/business/nouns/pay-run/approve) | Approve accepts a prepared Pay Run within the approver’s Mandate, books its cost, and schedules payment to land on the pay date. | [Payroll Specialist](/agents/people/payroll-specialist) | [`PayRun.approved`](/business/events/PayRun.approved) | One-way (money): `send`, `do` |
| [PayRun.pay](/business/nouns/pay-run/pay) | Pay funds an approved Pay Run: net pay to each employee’s bank on the pay date, taxes and deductions to the payroll provider. | [Treasurer](/agents/finance/treasurer) | [`PayRun.paid`](/business/events/PayRun.paid) | One-way (money): `send`, `do` |
| [PayRun.prepare](/business/nouns/pay-run/prepare) | Prepare computes one pay period’s gross pay, withholding, deductions and employer taxes for each employee, and holds the Pay Run for approval. | [Payroll Specialist](/agents/people/payroll-specialist) | [`PayRun.prepared`](/business/events/PayRun.prepared) | Two-way: `try`, `send`, `do` |
| [PayRun.void](/business/nouns/pay-run/void) | Void sets aside a prepared Pay Run that is wrong, so a corrected one can be prepared; the record stays. | [Payroll Specialist](/agents/people/payroll-specialist) | [`PayRun.voided`](/business/events/PayRun.voided) | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[PayRun.get](/business/nouns/pay-run/get) | Returns one Pay Run by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[PayRun.list](/business/nouns/pay-run/list) | Returns Pay Runs, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

A Pay Run is kept forever and never edited: it has no `update` or `delete`.

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `PayRun.get` | Yes | Yes | Yes | Yes |
| `PayRun.list` | Yes | Yes | Yes | Yes |
| `PayRun.approve` | Yes | No | No | No |
| `PayRun.pay` | Yes | No | No | No |
| `PayRun.prepare` | Yes | Yes | Yes | No |
| `PayRun.void` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Prepare the latest pay run with a company.
```

**API**

```bash
curl -X POST https://api.sb/tutorloop.com/pay-runs/prepare \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"company_1","periodStart":"2026-10-22","periodEnd":"2026-10-22","payDate":"2026-10-22"}'
```

```json
{
  "api": "https://api.sb/tutorloop.com",
  "payRun": {
    "$id": "https://api.sb/tutorloop.com/pay-runs/pay_run_1",
    "$type": "PayRun",
    "company": "company_1",
    "periodStart": "2026-10-22",
    "periodEnd": "2026-10-22",
    "payDate": "2026-10-22"
  },
  "action": {
    "$id": "https://api.sb/tutorloop.com/actions/action_1",
    "operation": "PayRun.prepare",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/tutorloop.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const payRun = await $.PayRun.prepare({ company: 'company_1', periodStart: '2026-10-22', periodEnd: '2026-10-22', payDate: '2026-10-22' })
```

**CLI**

```bash
npx startup-builder do PayRun.prepare --json '{"company":"company_1","periodStart":"2026-10-22","periodEnd":"2026-10-22","payDate":"2026-10-22"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.PayRun.prepare({ company: 'company_1', periodStart: '2026-10-22', periodEnd: '2026-10-22', payDate: '2026-10-22' })"
  }
}
```

## Example
A property-management app with four employees in two states pays on the 15th and the last day of each month. The [Payroll Specialist](/agents/people/payroll-specialist) prepares the run for the 1st to the 15th: $18,400 gross, withholding for both states, $14,050 net. It approves within its [Limit](/business/nouns/limit), and the [Treasurer](/agents/finance/treasurer) funds it two days before payday.