Skip to main content

Payroll Calculation API

Summary​

One native command calculates or recalculates an editable tenant-period run.

Audience​

Frontend and backend developers, QA and support engineers, architects, security reviewers, and implementation partners.

Reference Content​

Authentication: bearer context is expected for business APIs; service-local enforcement Requires confirmation. Authorization: no endpoint-specific Payroll Service role policy is confirmed. Maturity: Direct / Shadow.

OperationMethod and public routePurposeAuthenticationTenant contextRequest typeResponse typeSuccessMaturitySource path
Calculate payroll runPOST /payroll/runs/calculateCalculate or recalculate a Payroll run for a month and year.Bearer context expected; service-local enforcement Requires confirmationForwarded or explicit tenant context; exact missing-context mapping Requires confirmationPayrollRunCalculateRequestPayrollRunResponse200Directmicroservices/src/payroll-service/Api/PayrollRunEndpoints.cs

Calculate payroll run​

  • API family / maturity: Payroll Calculation API; Direct
  • Authentication / authorization: Bearer context expected; service-local enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
  • Tenant context: Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation.
  • Route parameters: None.
  • Query parameters: None.
  • Request body / type: month, year, optional tenantId; PayrollRunCalculateRequest.
  • Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
  • Response body / type: PayrollRunResponse.
  • Success / error responses: 200; 400 {message} for invalid month/year; 409 {message} when a frozen run blocks recalculation.
  • Business behavior: Calculate or recalculate a Payroll run for a month and year.
  • State and input implications: Creates/reuses an editable run and sets it Calculated. Loads workforce, Attendance, Leave, Expense, overtime, component, adjustment, statutory and advance inputs; missing Attendance skips that employee.
  • Audit and event implications: Persists calculation audit and timeline evidence. Stages a Payroll-calculated outbox event.
  • Compatibility notes: Native Payroll contract.
  • Safe example: POST /payroll/runs/calculate with {"month":7,"year":2026} → 200 run summary; invalid period → 400 {"message":"Invalid period."}
  • Example error: {"message":"Request could not be completed."} (illustrative safe wording)

Family-level findings​

Calculation may initialize the period and run. It replaces existing details/calculation rows for the chosen editable run. Frozen-period recalculation returns conflict. Formulas, rates, thresholds, and financial examples are intentionally excluded.

Source References​

  • microservices/src/payroll-service/Api/PayrollRunEndpoints.cs
  • microservices/src/payroll-service/Application/PayrollCalculationService.cs

See Also​

Keywords​

  • Payroll API
  • Payroll Calculation API

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-15
  • Review cycle: Quarterly