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.
Putting workers on a calendar
When you create or invite an employee, send payrollCalendarId to put them on one of the company's calendars. If you don't, they're put on the company's default calendar. The older paySchedule field still works but is deprecated, and you can't send both. An unknown calendar returns 404. A calendar that's archived, or that starts after the worker's start date, returns 422.
A worker's payrollCalendarId is returned on the worker, and you can pass payrollCalendarId to list workers to find everyone on a calendar.
To move an existing employee to another calendar, use Update payroll calendar with a payrollCalendarId:
- The change applies from the day after the worker's last finalized payment. Finalized payments are never changed. Everee deletes the worker's unfinalized payroll payments from that point onward and regenerates them on the new calendar, so a payment for a period that was already in progress is recalculated. There's no way to choose a different date.
- The calendar can't be archived, and must already be effective on the day regeneration starts.
- Contractors can't be put on a calendar, and neither can workers at companies that don't use payroll calendars. Both return
422. - Sending the calendar the worker is already on does nothing and returns
200.
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.