A payroll calendar defines the schedule of pay periods used to pay a company's workers: how often pay periods occur and which day they start. The Payroll Calendar API lets you list, create, rename and remove a company's payroll calendars.
| Endpoint | What it does |
|---|---|
| List payroll calendars | Lists the company's calendars |
| Retrieve a payroll calendar | Retrieves one calendar |
| Create a payroll calendar | Creates a calendar that takes effect on a future date |
| Rename a payroll calendar | Changes a calendar's name |
| Delete or archive a payroll calendar | Deletes a calendar, or archives it if it's in use |
Pay period types and start days
Which start day fields you send depends on the calendar's payPeriodType:
payPeriodType | Required | Not allowed |
|---|---|---|
WEEKLY, BI_WEEKLY | weeklyStartDay (MONDAY through SUNDAY) | monthlyStartDay |
SEMI_MONTHLY | monthlyStartDay, from 1 to 13 | weeklyStartDay |
MONTHLY | monthlyStartDay, from 1 to 28 | weeklyStartDay |
For SEMI_MONTHLY, monthlyStartDay is the start of the first pay period of the month. The second starts 15 days later, which is why the first can't be later than the 13th.
Effective date
A new calendar's effectiveDate must be tomorrow or later. You can't create a calendar that starts in the past or today.
Names
A calendar's displayName can be up to 255 characters, and must be unique among the company's active calendars, ignoring case. Creating or renaming a calendar to a name that's already taken returns 409. Archived calendars don't count, so their names can be reused. If a calendar was never given a name, its displayName is the title of its pay period type, like "Weekly".
Renaming is the only change you can make to an existing calendar. An archived calendar can't be renamed.
Deleting and archiving
DELETE removes a calendar if it's safe to, and archives it otherwise. It returns 204 in both cases, so retrieve the calendar afterwards if you need to know which happened. An archived calendar has an archiveDate.
A calendar is archived instead of deleted if any of these is true:
- workers are assigned to it
- it has pay periods
- it's the company's default calendar
Deleting a calendar that's already archived does nothing and returns 204.
Archived calendars are left out of the list unless you pass includeArchived=true. You can always retrieve one by ID.
Pagination and sorting
The list is paginated with page and size. See Pagination. Use sort to order the results by id, displayName, payPeriodType, effectiveDate or archiveDate, like sort=effectiveDate,desc. Any other property returns 400. By default calendars are sorted by effectiveDate, then id.