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

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

> The Pay Run Verbs approve, pay, prepare, void as api.sb routes, with inputs, result, refusals and an example.

Reference for [Pay Run](/business/nouns/pay-run), one group of [Pay Run routes](/code/api/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=api).

```text
POST /{namespace}/pay-runs/{payRun}/approve
```

Path: `payRun`. 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
curl -X POST https://api.sb/leaseline.app/pay-runs/payrun_hqqWu5rAyZ/approve \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "payRun": {
    "$id": "https://api.sb/leaseline.app/pay-runs/payrun_hqqWu5rAyZ",
    "$type": "PayRun",
    "company": "company_28zYNZEno0",
    "periodStart": "2026-10-22",
    "periodEnd": "2026-10-22",
    "payDate": "2026-10-22"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "PayRun.approve",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### 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=api).

```text
POST /{namespace}/pay-runs/{payRun}/pay
```

Path: `payRun`. 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
curl -X POST https://api.sb/leaseline.app/pay-runs/payrun_hqqWu5rAyZ/pay \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "payRun": {
    "$id": "https://api.sb/leaseline.app/pay-runs/payrun_hqqWu5rAyZ",
    "$type": "PayRun",
    "company": "company_28zYNZEno0",
    "periodStart": "2026-10-22",
    "periodEnd": "2026-10-22",
    "payDate": "2026-10-22"
  },
  "transaction": {
    "$id": "https://api.sb/leaseline.app/transactions/txn_XoxtZe3CQI",
    "$type": "Transaction",
    "kind": "charge",
    "amount": {
      "amount": 29,
      "currency": "USD"
    }
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "PayRun.pay",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### 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=api).

```text
POST /{namespace}/pay-runs/prepare
```

Body, as JSON: the inputs. 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
curl -X POST https://api.sb/leaseline.app/pay-runs/prepare \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"company_28zYNZEno0","periodStart":"2026-10-22","periodEnd":"2026-10-22","payDate":"2026-10-22"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "payRun": {
    "$id": "https://api.sb/leaseline.app/pay-runs/payrun_hqqWu5rAyZ",
    "$type": "PayRun",
    "company": "company_28zYNZEno0",
    "periodStart": "2026-10-22",
    "periodEnd": "2026-10-22",
    "payDate": "2026-10-22"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "PayRun.prepare",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### 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=api).

```text
POST /{namespace}/pay-runs/{payRun}/void
```

Path: `payRun`. Body, as JSON: the other inputs. 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
curl -X POST https://api.sb/leaseline.app/pay-runs/payrun_hqqWu5rAyZ/void \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Example reason"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "payRun": {
    "$id": "https://api.sb/leaseline.app/pay-runs/payrun_hqqWu5rAyZ",
    "$type": "PayRun",
    "company": "company_28zYNZEno0",
    "periodStart": "2026-10-22",
    "periodEnd": "2026-10-22",
    "payDate": "2026-10-22"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "PayRun.void",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```