Skip to main content
The STE tracks four time horizons for wages and withholding.

​
What each surface calls them

The four horizons are the same concept on both surfaces, but only the on-premise SDK names the current period “CTD.”
The hosted API has no ctdWages field. Current-period wages are just grossWages, and the CTD label reappears only on the output side.
Prior withholding is passed separately from wages, per tax. On the hosted API those are periodWH, mtdWH, qtdWH, and ytdWH on each taxJurisdictionParms entry.

​
The critical convention: inputs exclude the current period, outputs include it

Inputs you provide are prior period-to-date figures — they exclude the current check. The results the engine returns are inclusive — they include the current check. Mixing these up double-counts the current period.
Concretely: to calculate the third biweekly check of the year, you pass the current check’s wages as the current-period figure — grossWages on the hosted API, ctd in the SDK — and the sum of the first two checks as YTD. The engine adds them internally and returns a YTD figure that now includes all three. A $3,000 check with ytdWages of $6,000 returns "subjectWagesYTD": 9000 on Social Security. Which of these figures a given tax reports is a separate question, covered next.

​
Which period-to-date figures come back

The period-to-date fields on a result are there to show how far an employee has progressed toward a tax’s limit. They are limit-tracking figures rather than general wage totals, so the engine fills in only the ones a given tax needs. Federal income tax has no wage base, so it returns 0 for all six. Social Security returns current-period and year-to-date figures but never quarterly ones, even when the employee is past the wage base and the excess wages are real.
A 0 in these fields usually means the figure was not calculated for that tax, not that there were no wages. The amounts returned for every tax are grossWages, grossSubjectWages, subjectWages, and taxAmount.

​
Why the engine needs prior period-to-date figures

Several calculations are impossible without accurate YTD/QTD context:
  • Wage-base limits — Social Security, FUTA, and SUTA stop taxing once YTD wages cross the annual cap. The engine needs prior YTD to know how much room is left.
  • Progressive brackets & annualization — cumulative methods (NY, NJ) tax YTD wages and subtract prior withholding, smoothing period-to-period variance.
  • Benefit and contribution limits — annual 401(k)/HSA caps are enforced against YTD contributions.
  • Additional Medicare — the extra 0.9% kicks in only after YTD wages cross the threshold.
Because wage bases and limits are annual, YTD is the most important horizon to get right. QTD matters for unemployment taxes, which report quarterly. MTD is accepted for the taxes that need it, but never returned. When in doubt, always supply accurate YTD.

Gross, subject & taxable wages

What these amounts represent.

Setting wages

Passing period-to-date figures.