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

# Managing Pay Schedules

## Overview

A payroll schedule determines the length of your pay period and how often you pay your employees. The most common payroll schedules are weekly, biweekly, semimonthly, and monthly. Your payroll schedule is dependent upon a few factors, including provincial laws and regulations. Many provinces have pay schedule frequency requirements that you’ll need to meet.

On top of provincial laws, your pay schedule should also fit the needs of your employees and your business. If you employ mostly hourly workers, your pay schedule may look different from a business with mostly salaried employees. Your province, your industry, and the types of workers you employ all impact your payroll schedule.

Typical pay frequencies include:

* Weekly
* Bi-weekly
* Semi-monthly
* Monthly

Each frequency type requires specific configuration parameters.

***

## Pay Schedule Parameters

| Field                      | Type                      | Required    | Description                                                                                                                                      |
| -------------------------- | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`                    | string                    | Yes         | The label used for this Pay Schedule.                                                                                                            |
| `pay_frequency`            | enum                      | Yes         | Must be one of `weekly`, `bi-weekly`, `semi-monthly`, `monthly` or `custom`.                                                                     |
| `anchor_pay_date`          | ISO8601 date (YYYY-MM-DD) | Yes         | First intended pay date (before weekend/holiday movement).                                                                                       |
| `anchor_end_of_pay_period` | ISO8601 date (YYYY-MM-DD) | Yes         | Final day of the first earning period.                                                                                                           |
| `day_1`                    | integer                   | Conditional | On `monthly` or `semi-monthly` schedules, the numeric day of month for the first payroll.                                                        |
| `day_2`                    | integer                   | Conditional | On `semi-monthly`, the numeric day in the month for the second payroll.                                                                          |
| `pay_day_movement_setting` | enum                      | No          | Determines how pay dates are adjusted for holidays or weekends. Defaults to `inherit`.                                                           |
| `generate_payrolls_from`   | ISO8601 date (YYYY-MM-DD) | No          | Available for Business Entities in Preview mode, must be on or after `anchor_pay_date`. Allows for creation of Payrolls before the current date. |

### Pay Day Movement Options

* `inherit` (default): Use the Business Entity setting.
* `previous_business_day`: Move to the previous working day.
* `next_business_day`: Move to the next working day.

### Custom Pay Schedules

For more information on Custom Pay Schedules, please see the\
[Custom Pay Schedules](/guides/advanced/custom-pay-schedules) guide.

***

## Creating a Pay Schedule

### Endpoint

`POST /services/payroll/pay_schedules`

### Request Example

```bash theme={null}
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/pay_schedules \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
         "title": "Salary Schedule",
         "pay_frequency": "semi-monthly",
         "anchor_pay_date": "2025-01-15",
         "anchor_end_of_pay_period": "2025-01-15",
         "day_1": 15,
         "day_2": -1,
         "business_entity_id": "01hhcy3fpqkez7wjqzeaqetwfs"
     }'
```

### Success Response

```json theme={null}
{
  "id": "01hhcy3ftxe4wrcsyzf7a3a46q",
  "object": "pay_schedule",
  "data": {
    "title": "Salary Schedule",
    "pay_frequency": "semi-monthly",
    "anchor_pay_date": "2025-01-15",
    "anchor_end_of_pay_period": "2025-01-15",
    "day_1": 15,
    "day_2": -1,
    "pay_day_movement_setting": "inherit",
    "created_at": "2025-12-11T17:16:56Z",
    "updated_at": "2025-12-11T17:16:56Z"
  },
  "links": {
    "self": "https://sandbox.nmbr.co/services/payroll/pay_schedules/01hhcy3ftxe4wrcsyzf7a3a46q"
  }
}
```

### Error Response Example

```json theme={null}
{
    "message": "The selected pay frequency is invalid (and 1 more error)",
    "errors": {
        "pay_frequency": [
            "The selected pay frequency is invalid."
        ],
        "anchor_pay_date": [
          "The anchor pay date field is required unless pay frequency is in custom."
        ]
    }
}
```

***

## Behavior by Pay Frequency

### Weekly

* Projects payrolls weekly based on the weekday value of `anchor_pay_date` and `anchor_end_of_pay_period`.

### Bi-Weekly

* Projects payrolls every two weeks based on the weekday value of `anchor_pay_date` and `anchor_end_of_pay_period`.

### Semi-Monthly

* Two pay periods per month.
* Supports two configurations:
  * 15th and last day of the month - `day_1` of `15`, `day_2` of `-1`.
  * 16th and 1st of the month - `day_1` of `16`, `day_2` of `1`.
* If `day_1` or `day_2` would fall on an invalid date (e.g., September 31st), the payroll's `calculated_pay_date` will be adjusted to the prior valid date.

### Monthly

* One payroll per month.
* `day_1` defines the pay date. Use `-1` to indicate *"last day of the month"*.
* If `day_1` would fall on an invalid date (e.g., September 31st), the payroll's `calculated_pay_date` will be adjusted to the prior valid date.

***

## Notes

* **Date Validations:** Invalid dates automatically roll back to the nearest valid day.
* **Pay Date adjustment:** If the payrolls `calculated_pay_date` falls on a weekend or holiday, the payrolls `pay_date` will be adjusted to a valid date based on the `pay_day_movement_setting`.
* **Defaults:** If `pay_day_movement_setting` is not provided, the Business Entity default is used.