# Pay Run commands: approve, pay, prepare, void

URL: /code/cli/pay-run/verbs · Id: `page:code/cli/pay-run/verbs`

> The Pay Run Verbs approve, pay, prepare, void as CLI commands, with inputs, result, refusals and an example.

Reference for [Pay Run](/business/nouns/pay-run), one group of [Pay Run commands](/code/cli/pay-run).

### PayRun.approve
Approve accepts a prepared Pay Run within the approver’s Mandate, books its cost, and schedules payment to land on the pay date. [Verb page](/business/nouns/pay-run/approve?interface=cli).

```text
npx startup-builder do PayRun.approve --json '<input>' [--try | --send | --do]
```

Emits [`PayRun.approved`](/business/events/PayRun.approved).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The prepared Pay Run. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The approved Pay Run, scheduled for its pay date. |

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

**Example**

```bash
npx startup-builder do PayRun.approve --json '{"payRun":"payrun_hqqWu5rAyZ"}'
```

### PayRun.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. [Verb page](/business/nouns/pay-run/pay?interface=cli).

```text
npx startup-builder do PayRun.pay --json '<input>' [--try | --send | --do]
```

Emits [`PayRun.paid`](/business/events/PayRun.paid).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The approved Pay Run. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The paid Pay Run. |
| `transaction` | [Transaction](/business/nouns/transaction) | Yes | The funding Transaction. |

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

**Example**

```bash
npx startup-builder do PayRun.pay --json '{"payRun":"payrun_hqqWu5rAyZ"}'
```

### PayRun.prepare
Prepare computes one pay period’s gross pay, withholding, deductions and employer taxes for each employee, and holds the Pay Run for approval. [Verb page](/business/nouns/pay-run/prepare?interface=cli).

```text
npx startup-builder do PayRun.prepare --json '<input>' [--try | --send | --do]
```

Emits [`PayRun.prepared`](/business/events/PayRun.prepared).

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

**Returns**

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

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

**Example**

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

### PayRun.void
Void sets aside a prepared Pay Run that is wrong, so a corrected one can be prepared; the record stays. [Verb page](/business/nouns/pay-run/void?interface=cli).

```text
npx startup-builder do PayRun.void --json '<input>' [--try | --send | --do]
```

Emits [`PayRun.voided`](/business/events/PayRun.voided).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The prepared Pay Run. |
| `reason` | `text` | Yes | Why it was set aside. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The voided Pay Run. |

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

**Example**

```bash
npx startup-builder do PayRun.void --json '{"payRun":"payrun_hqqWu5rAyZ","reason":"Example reason"}'
```