Skip to content

Payroll Calendars

The payroll calendar describes how payroll runs are mapped to the calendar. The system culture serves as the basis. The payroll calendar determines the frequency of wage payments through the wage cycle, the wage period, and the weekly and annual definitions. Each tenant has one or more calendar definitions that are referenced by different objects.

The payroll calendar is the basis for case fields with the time type Period and CalendarPeriod.

Calendar Types

The payroll calendar divides business data into two time units:

  • Period — the interval in which the salary is paid, usually the calendar month (PeriodTimeUnit).
  • Cycle — the interval in which the salary periods repeat, usually the calendar year (CycleTimeUnit).

The cycle time unit is always a multiple of the period time unit.

The following overview shows the possible combinations of the two time units with the number of wage payments per cycle.

Cycle →
Period ↓
 Wk Bi-Wk Semi-Mo Lunar Mo Bi-Mo Qtr Semi-Yr Yr
Week 1 2 - 4 - - 13 26 52
Bi-Week - 1 - 2 - - - 13 26
Semi-Month 3) - - 1 - 2 4 6 12 24
Lunar-Month - - - 1 - - - - 13
Month 1) - - - - 1 2 3 6 12 4)
Bi-Month 2) - - - - - 1 - 3 6
Quarter 2) - - - - - - 1 2 4
Semi-Year 2) - - - - - - - 1 2
Year 2) - - - - - - - - 1

1) Override the effective number of days in the calendar month with a configurable average.
2) Fiscal years with the year starting on any calendar month.
3) Month breakdown: 1 to 15 and 16 to end of month.
4) Default payroll calendar.

Calendar Example

Example of different payroll calendars: 

calendars:
- name: YearlySalary
  cycleTimeUnit: Year
  periodTimeUnit: CalendarMonth
  timeMap: Cycle           # values apply to the full cycle: annual wages
- name: MonthlySalary
  cycleTimeUnit: Year
  periodTimeUnit: CalendarMonth
  timeMap: Period          # values apply to each period: monthly wages
- name: QuarterSalary
  cycleTimeUnit: Year
  periodTimeUnit: Quarter
  firstMonthOfYear: April  # fiscal year starts in April
  timeMap: Period          # values apply to each period: quarterly wages

Calendar Resolution Order

The calendar is resolved during the payrun according to the following priority: 1. Wage Type 2. Employee 3. Division 4. Tenant

World Time

All date values in the REST API must be specified in UTC. Other time zones will result in errors.

Calendar Configuration

The calendar is configured with the following settings:

  • Cycle time unit
  • Period time unit
  • Time mapping — cyclic or periodic, examples:
  • Cycle=Year, Period=Month, Base value=60,000 → Payroll value=5,000
  • Cycle=Semi-year, Period=Bi-Week, Base value=52,000 → Payroll value=4,000
  • First month of year for fiscal years (default: January)
  • Rule for determining the first week of the year
  • First day of the week (default: Monday)
  • Average number of days in a month
  • Definition of working days in a week (e.g. Monday to Friday)

Payrun Time Value Calculation

When calculating a period value, all relevant mutations within the period are distributed proportionally according to the calendar (e.g. mid-month salary adjustments). The Scripting API provides access to the calendar's distribution logic, which significantly simplifies the calculation syntax. Two case values with different mutations can be combined using the standard mathematical operators (addition, subtraction, multiplication, division).

See Time Data for details on time types and time calculations.