# prepare

URL: /business/nouns/pay-run/prepare · Id: `verb:PayRun.prepare` · Call: `await $.PayRun.prepare({ … })` (SDK) or the `do` tool at `https://api.sb/mcp`. Inputs says what to pass, Outputs what returns, When it waits who approves.

> Prepare computes one pay period’s gross pay, withholding, deductions and employer taxes for each employee, and holds the Pay Run for approval.

Prepare computes one pay period’s gross pay, withholding, deductions and employer taxes for each employee, and holds the [Pay Run](/business/nouns/pay-run) for approval.

## Inputs
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `company` | [Company](/business/nouns/company) | Yes | The employer Company. |
| `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 should land. |
| `kind` | `string` | No | Defaults to `regular`; `offCycle` pays outside the schedule. |
| `humans` | list of [Human](/business/nouns/human) | No | Only these employees. Defaults to every employee of the Company. |

## Outputs
| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The prepared Pay Run, with every amount per employee. |

## Effects
- Emits [`PayRun.prepared`](/business/events/PayRun.prepared).
- Performed by the [Payroll Specialist](/agents/people/payroll-specialist).
- Two-way: it runs at once, in the `try`, `send` and `do` modes.
- Reads each employee’s pay rate from their employment Agreement and withholds for the state where they work.
- Adds the Benefits deductions each employee elected.
- Opens a Task for the Payroll Specialist when a rate, a tax setup or a bank account is missing.

## Refuses when
| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | [PayRun.prepare](/business/nouns/pay-run/prepare) |

## When it waits
| Gate | Default |
| --- | --- |
| Decision class | Low: two-way, nothing at stake |
| [Delay window](/systems/trust-and-governance/controls/one-way-windows) | None: it runs once review passes. |
| Limit | The call [Limit](/business/nouns/limit) of the [Permission](/business/nouns/permission) it runs under. |
| Over the Limit | It waits `pending` for an [Approval](/business/nouns/approval) from the [Founder](/agents/founding/founder). Approved, it runs; refused, it ends `refused` with [`limit-exceeded`](/code/api/errors/limit-exceeded); unanswered by its deadline, it ends `canceled`. |

## Example

**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' })"
  }
}
```

Next: [`PayRun.approve`](/business/nouns/pay-run/approve) (in `guide:run-payroll`).

Guides that call it: [Run payroll](/systems/people/run-payroll).