> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rollfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Payroll Guide

## 🔹 Pay Schedules

A pay schedule defines how often employees are paid and the specific dates associated with each pay period.

**Available Frequencies:** Weekly, BiWeekly, SemiMonthly, Monthly

### Configuration

* Pay schedules are typically configured during company onboarding but can be updated later.
* Only one active pay schedule is allowed per worker type (W2 or 1099).
* Payrolls can be **self-initiated** or **automatic** (most common) based on company preference.
* Employees are automatically included in payrolls based on their active status and pay schedule.
* Pay is automatically calculated based on employee configurations, including wages, benefits, and elections.

### Monthly and SemiMonthly pay schedules

**Step 1:** Since Monthly and SemiMonthly paySchedules naturally follow a calendar, pay period start and end dates should first be retrieved using [getMonthlyAndSemiMonthlyPayScheduleDates](https://developer.rollfi.xyz/api-reference/reports/getMonthlyAndSemiMonthlyPayScheduleDates)

**Step 2:** Decide on a pay date for the schedule. The following fields determine what day your employees will be paid

🗓️ Monthly

* Use `payDay` to determine when employees will recieve their pay
* Supported `payDay` values: “Last day of the month” or “N day(s) after pay period ends” (1–31).

🗓️ SemiMonthly

* Use `payDateOptions` to determine when employees will recieve their pay
* Supported `payDateOptions`: “15th and last day of the month” or “N days From payEndDate”.
* We currently allow `payDateOptions` to be set up to 7 days from payEndDate.

⚠️ Warning - The changes above replace the `option` field for Monthly and SemiMonthly pay schedules will soon be deprecated. These changes allow the company to set the date their employees will be paid on, without having to adhere to a strict calendar.

### Quarterly pay schedules

* The first day of the paySchedule, and first generated payPeriod is decided by the included `payDate`
* Using a payDate during the current quarter will backdate the paySchedule and immediately generate a payPeriod
* To ensure payPeriods begin when you require, payDate must lie between the following dates

| First Pay Period | Dates         |
| ---------------- | ------------- |
| Q1               | 01/01 - 03/31 |
| Q2               | 04/01 - 06/30 |
| Q3               | 07/01 - 09/30 |
| Q4               | 10/01 - 12/31 |

## 🔹 Supplemental Payroll

When a payroll falls outside a regular pay schedule, it is considered a **supplemental payroll**.

Supplemental payrolls are useful for companies with unique or irregular pay needs (e.g., project-based or off-cycle payments).

### Adding a Supplemental Pay Period

A supplemental pay period can be created at any time using the [addSupplementalPayPeriod](https://developer.rollfi.xyz/api-reference/payroll/addsupplementalpayperiod) API, regardless of existing pay schedules.

#### Pay Period Types

| Pay Period Type | Description                                                                       |
| --------------- | --------------------------------------------------------------------------------- |
| **Missing**     | Pay periods not recorded in the system due to cancellations or processing errors. |
| **Dismissal**   | Final paychecks or severance pay for terminated employees.                        |
| **Off-Cycle**   | General pay period for employees paid outside the normal schedule.                |

⚠️ Note - `payEndDate` and `payDate` must be **future dates** to allow time for adjustments, initiation, and processing.

#### Additional Details:

* Once created, employees can be added using [addUsersToSupplementalPayPeriod](https://developer.rollfi.xyz/api-reference/payroll/addUsersToSupplementalPayPeriod).
* Employees may belong to multiple supplemental pay periods.
* Supplemental pay periods follow the **standard payroll processing workflow**, including adding or removing payroll items.

***

## 🔹 Pay Period Adjustments

Adjustments allow modification of payroll data **before** the pay period is submitted for processing.

Adjustments can include adding or removing employees, modifying wages, bonuses, deductions, and other compensation items.

### Adding Adjustments

Adjustments can be added to a pay period using the [importRegularPayrollData](https://developer.rollfi.xyz/api-reference/payroll/importRegularPayrollData) API.

This endpoint allows you to import or update regular payroll data such as employee wages, hours worked, deductions, reimbursements, bonuses, and other compensation details for a specific pay period.

### Removing Adjustments

Use the following APIs to remove previously applied adjustments from a pay period:

* [removeDeductions](https://developer.rollfi.xyz/api-reference/payroll/removeDeductions)
* [removeAdditionalCompensations](https://developer.rollfi.xyz/api-reference/payroll/removeAdditionalCompensations)
* [removeReimbursements](https://developer.rollfi.xyz/api-reference/payroll/removeReimbursements)
* [removeOvertime](https://developer.rollfi.xyz/api-reference/payroll/removeOvertime)

***

## 🔹 Changing Payment Methods

Payment methods for employees in open pay periods can also be updated through payroll import.

Use either of the following APIs and include `paymentMethod` on the employee record:

* [importRegularPayrollData](https://developer.rollfi.xyz/api-reference/payroll/importRegularPayrollData)
* [importRegularDifferentialPayrollData](https://developer.rollfi.xyz/api-reference/payroll/importRegularDifferentialPayrollData)

Notes:

* Supported values are `Check` and `Direct Deposit`.
* If `paymentMethod` is omitted, payroll uses the employee's existing default payment method.
* `Direct Deposit` requires an active employee bank account. If no active bank account is available, the payment method change is skipped for that employee.
* Payment method changes apply to open pay periods that are still editable.

***

## 🔹 Processing Payroll

When a payroll is submitted, it progresses through several stages before employee funds are disbursed.\
Each stage has a specific **status** that indicates where the payroll is in the process.

For a detailed overview of payroll statuses and lifecycle, refer to the [Payroll Processing Guide](https://developer.rollfi.xyz/docs/PayrollProcessing).