Skip to content

Retro Corrections

A retro correction arises when a case value change is entered with an effective date in a period that has already been processed by a payrun. PayrollEngine detects the discrepancy, re-executes the affected historical payrun periods, and settles the accumulated difference in the current period's payslip as a retro value.

How retro corrections are triggered

The engine compares the set of case values visible at the original payrun's evaluationDate against the values visible now. When a ValueChange mutation is detected — a case field value that was absent or different during the original run — the engine creates retro payrun jobs for each affected historical period.

{
  "caseName": "MonthlyWage",
  "values": [{
    "caseFieldName": "MonthlyWage",
    "value": "6000",
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-02-28T00:00:00Z",
    "created": "2025-03-15T00:00:00Z"
  }]
}

In this example the case change was created on 2025-03-15. The January payrun had evaluationDate = 2025-02-01 and the February payrun had evaluationDate = 2025-03-01 — both predating the created timestamp. The March payrun (evaluationDate = 2025-04-01) sees the new value and triggers retro jobs for January and February automatically.

What the retro value represents

The RetroValue on a payslip is the net correction that must be paid to or deducted from the employee in the current period to compensate for the recalculated historical amounts:

RetroValue = Σ (ConsolidatedValue(m) − OriginalValue(m))   for m = 1..month-1
  • ConsolidatedValue(m) — final value for period m after retro recalculation, returned by GetConsolidatedWageTypeResults without an EvaluationDate constraint.
  • OriginalValue(m) — value that was stored when the period was first processed, obtained by passing EvaluationDate = start of m+1 to the same endpoint. The engine returns only results visible at that point in time, excluding any later corrections.

A positive RetroValue means the employee was underpaid in prior periods; a negative value means they were overpaid.

Why retro values must not be computed in the payrun

Retro values are derived by comparing two sets of consolidated results across multiple periods. Computing this inside payrun wage type expressions:

  • Requires executing GetConsolidatedWageTypeResults (an expensive multi-period aggregation query) for every prior period, inside the hot path of every payrun job
  • Creates a circular dependency: the correction depends on stored results that the current payrun is in the process of generating
  • Cannot be correctly re-evaluated during a retro recalculation of the same period

Exception: A regulation may include a dedicated delta wage type that collects the retro correction sum for payout in the current period. This wage type uses the RetroSum accessor (GetRetroWageTypeValueSum) which reads directly from the engine's internal retro result buffer — it does not query consolidated results and is safe to use inside payrun execution. Delta wage types must be assigned to the Legal cluster only, never to Retro, so they execute exactly once in the current period.

Storing baseline results

Retro correction magnitude is computed as the difference between the recalculated result and the stored original result. If no result was stored for a period, the engine treats the prior value as zero — the full recalculated amount becomes the correction.

Set storeEmptyResults: true on all payrun jobs in a regulation that uses retro recalculation. This ensures a baseline result exists for every employee in every period, even when the calculated value is zero. A correction that arrives later will then produce the correct signed delta rather than the full recalculated value.

Retro and period totals together

RetroValue and YtdValue are independent columns computed by separate aggregation paths. YtdValue sums ConsolidatedValue(m) across all months including corrections; RetroValue sums the signed delta between consolidated and original for prior months only. The net pay line on a payslip uses CurrentValue + RetroValue; the YTD column always shows the corrected cumulative total.

See Also