Skip to main content

Payroll Freeze and Unfreeze API

Summary​

Two native commands establish and reverse the stable Payroll run boundary.

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
Freeze payroll runPOST /payroll/runs/{id:guid}/freezeFreeze an existing run.Bearer context expected; service-local enforcement Requires confirmationForwarded or explicit tenant context; exact missing-context mapping Requires confirmationRoute and query parametersPayrollRunResponse200Directmicroservices/src/payroll-service/Api/PayrollRunEndpoints.cs
Unfreeze payroll runPOST /payroll/runs/{id:guid}/unfreezeReopen a Frozen native run.Bearer context expected; service-local enforcement Requires confirmationForwarded or explicit tenant context; exact missing-context mapping Requires confirmationRoute and query parametersPayrollRunResponse200Directmicroservices/src/payroll-service/Api/PayrollRunEndpoints.cs

Freeze payroll run​

  • API family / maturity: Payroll Freeze and Unfreeze 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: Required GUID runId.
  • Query parameters: Optional tenantId.
  • Request body / type: None; Route and query parameters.
  • 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; 404 {message} when missing; 409 {message} for invalid state, missing details, duplicate recovery, or insufficient recovery balance.
  • Business behavior: Freeze an existing run.
  • State and input implications: Marks run/details Frozen and enables frozen-only outputs. Applies planned advance recoveries; no Attendance/Leave/Expense mutation.
  • Audit and event implications: Persists lifecycle audit and timeline evidence. Stages a Payroll-frozen outbox event.
  • Compatibility notes: Native Payroll contract.
  • Safe example: POST /payroll/runs/{id:guid}/freeze → 200 with status:"Frozen"; repeated freeze → 409 {"message":"Run cannot be frozen."}
  • Example error: {"message":"Request could not be completed."} (illustrative safe wording)

Unfreeze payroll run​

  • API family / maturity: Payroll Freeze and Unfreeze 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: Required GUID runId.
  • Query parameters: Optional tenantId.
  • Request body / type: None; Route and query parameters.
  • 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; 404 {message} when missing; 409 {message} unless current state is Frozen.
  • Business behavior: Reopen a Frozen native run.
  • State and input implications: Marks run/details Unfrozen and removes frozen eligibility. Reverses unreversed local advance-recovery transactions.
  • Audit and event implications: Persists lifecycle audit and timeline evidence. Stages a Payroll-unfrozen outbox event.
  • Compatibility notes: Native Payroll contract.
  • Safe example: POST /payroll/runs/{id:guid}/unfreeze → 200 with status:"Unfrozen"; invalid state → 409 {"message":"Run cannot be unfrozen."}
  • Example error: {"message":"Request could not be completed."} (illustrative safe wording)

Family-level findings​

Native unfreeze uses Unfrozen; the salary compatibility operation uses Draft and different recovery behavior. Freeze is not payment execution, settlement, or irreversible finalization.

Source References​

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

See Also​

Keywords​

  • Payroll API
  • Payroll Freeze and Unfreeze API

Revision Information​

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