---
title: "Calculate Payroll Run"
method: POST
path: "/companies/{company_id}/payroll/runs/{run_id}/calculate"
tags: ["payroll"]
---

# Calculate Payroll Run

`POST /companies/{company_id}/payroll/runs/{run_id}/calculate`

## Request

- Base URL: `https://app.zeno-works.ch` (the document declares no server; this is the origin it was published from)
- URL: `https://app.zeno-works.ch/companies/{company_id}/payroll/runs/{run_id}/calculate`
- Auth: none declared

Compute the run — draft → ``calculated``; a recalculation keeps the state.

The totals appear **twice, and agree numerically** (ZET-265): the top-level
``employee_count`` / ``gross_total`` / ``net_total`` are this calculation's, and
the nested ``run`` carries the same three read back off the persisted results —
the figures the runs list and the run detail report for this run. So no second
call is needed to find out what was computed. **Compare them as decimals, not as
strings**: the read-back carries the stored column's scale (``6000.0000``) and the
top-level totals the engine's (``6000.00``).

## Path parameters

- `company_id` string, required
- `run_id` string, required

## Headers

- `authorization` string, nullable

## Cookies

- `access_token` string, nullable

## Request body

- PayrollCalculateRequest
  - `manual_inputs` PayrollManualInputIn[], nullable
    - `employee_id` string, required
    - `wage_type_code` string, required
    - `amount` union
      - number
      - string
    - `quantity` union
      - number
      - string
    - `unit_rate` union
      - number
      - string
    - `description` string, nullable

## Response `200`

Successful Response

- PayrollCalculateResponse
  - `run` PayrollRunOut, required
    - `id` string, required
    - `period_start` string, date, required
    - `period_end` string, date, required
    - `payment_date` string, date, nullable
    - `status` 'draft' | 'calculated' | 'approved' | 'posted' | 'paid' | 'locked' | 'reversed', required: Run lifecycle (payroll SP0; enforced from SP6 via ``invoiage_core.payroll.states``).
    - `run_kind` 'regular' | 'correction' | 'reversal', required: Run kind: corrections/reversals are separate runs, never in-place edits.
    - `journal_entry_id` string, nullable
    - `created_at` string, date-time, required
    - `calculated_at` string, date-time, nullable
    - `approved_at` string, date-time, nullable
    - `posted_at` string, date-time, nullable
    - `paid_at` string, date-time, nullable
    - `locked_at` string, date-time, nullable
    - `payment_batch_ref` string, nullable
    - `original_run_id` string, nullable
    - `reversed_by_run_id` string, nullable
    - `validated_at` string, date-time, nullable
    - `error_count` integer
    - `warning_count` integer
    - `employee_count` integer
    - `gross_total` string, nullable
    - `net_total` string, nullable
    - `staleness` PayrollStalenessOut: Why this artefact no longer matches the live master data. Absent (``null``) means "not stale". Never blocks anything: a correction over a locked or filed period is reported here, never refused (refusing would restore the dead end ZET-123 fixed).
      - `reasons` string[]
      - `action` string, nullable
      - `changed_fields` string[]
      - `audit_id` string, nullable
      - `changed_at` string, date-time, nullable
      - `reason` string, nullable
  - `findings` PayrollFindingOut[], required
    - `check` string, required
    - `severity` string, required
    - `message` string, required
    - `employee_id` string, nullable
  - `snapshot` PayrollSnapshotMetaOut, required
    - `id` string, required
    - `schema_version` integer, required
    - `engine_version` string, nullable
    - `payload_hash` string, required
    - `created_at` string, date-time, required
  - `gross_total` string, required
  - `net_total` string, required
  - `payout_total` string, required
  - `employer_total` string, required
  - `employee_count` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/zeno-works/apis/zeno-api.md) · [All operations](https://skmtc.dev/zeno-works/apis/zeno-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zeno-works/apis/zeno-api/revisions/1eb93dde146c?raw)