> ## 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.

# Custom Pay Schedules

Nmbr supports **Custom Pay Schedules** to offer flexible payroll cycles for businesses with non-standard payment needs.

> ℹ️ Enabling Custom Pay Schedules
> This feature is not enabled by default. To enable it, please contact [support@nmbr.co](mailto:support@nmbr.co).

Custom Pay Schedules have the following rules:

* **No fixed frequency**: They do not follow a recurring pattern like weekly or monthly schedules.
* **Work Assignment required**: Each Employee or Contractor must be assigned a Work Assignment linked to the Custom Pay Schedule.
* **Manual payroll creation**: Payrolls and Pay Stubs must be created manually.
* **Explicit parameters**: When creating a Payroll, you must specify `period_start`, `period_end`, `original_pay_date`, and `custom_pay_frequency`.
* **Overlapping allowed**: Payrolls can overlap in both earning periods and pay dates.
* **Strict ordering**: Payrolls must be processed in date order based on `pay_date`.
* **Frequency affects taxes**: `custom_pay_frequency` can vary between Payrolls, but may impact the accuracy of tax calculations.

## Creating Payrolls and Pay Stubs

Custom Pay Schedules do not auto-generate payrolls, unlike standard pay schedules. Instead, you must create payrolls manually. This allows for greater flexibility in managing payroll cycles, but also requires more attention to detail.

When creating a Payroll, you must specify the following parameters:

* `period_start` - the first day of the earning period.
* `period_end` - the last day of the earning period.
* `original_pay_date` - the pay date, ignoring weekends and holidays.
* `custom_pay_frequency` - the expected frequency for this payroll. This is used for tax calculations on this Payroll instance. This must be one of `weekly`, `bi-weekly`, `semi-monthly`, or `monthly`.

When creating a Payroll, Nmbr will generate the actual `pay_date` based on the `original_pay_date` and the Pay Schedule’s `pay_day_movement_setting`, adjusting for weekends and holidays.

Employees and Contractors require a Work Assignment to be assigned to a Pay Schedule, as on a standard Pay Schedule. However, no Pay Stubs are auto-generated on any Payroll in the Custom Pay Schedule, and must be created using the API.

## Pay Rates

Work Assignments on a Custom Pay Schedule may have Pay Rates, similar to standard Pay Schedules. Similarly, a Pay Stub will have managed Earning Line Items created for the Pay Rate.

However, as Custom Pay Schedules have no standard hours to apply, Earning Line Items will always have a `managed_hours` of `0`.

If `custom_hours` is set, the `managed_amount` is calculated using the derived hourly rate and the `custom_hours` value. The hourly rate is determined as:

```
Hourly Rate = annual-salary / 52 / expected_hours_per_week
```

## Allowances, Reimbursements, Benefits and Deductions

Custom Pay Schedules support Allowances, Reimbursements, Benefits and Deductions. These are created in the same way as standard Pay Schedules.

However, they can only use a frequency of `once` or `per_payroll`. The `per_month` frequency is not supported.

## Tax Calculation

When a Payroll is created, the `custom_pay_frequency` is used to determine the **expected frequency** of this Payroll within the calendar year.

To calculate Statutory Withholdings on a Pay Stub, Nmbr must estimate how many payrolls remain in the year. These estimates are based solely on the current Payroll’s attributes, since Custom Pay Schedules do not follow a fixed pattern.

The following attributes are estimated using `custom_pay_frequency`, `original_pay_date`, and `pay_date`:

* **`regular_periods_count`** – The estimated total number of payrolls in the year for this frequency.
* **`period_number`** – The estimated position of this Payroll in the year, regardless of how many payrolls have actually occurred to date.

### Frequency Estimation Rules

Each `custom_pay_frequency` uses a different method to estimate the period count:

* **`weekly`** – Based on the weekday of `original_pay_date`, counts how many times that weekday occurs in the year (adjusted for pay day movement due to weekends and holidays).

* **`bi-weekly`** – Starting from `original_pay_date`, counts every 14-day interval (same weekday) in the year to estimate how many bi-weekly pay days occur. Adjusts for holidays and weekends.

* **`semi-monthly`** – `regular_periods_count` is fixed at 24. `period_number` is calculated based on the month and whether the `original_pay_date` falls on or before the 15th (first period) or after (second period).

  > **Note:** If the `pay_date` is adjusted across year boundaries due to holidays or weekends, `period_number` is calculated relative to the new year.

* **`monthly`** – Based on the day of the month in `original_pay_date`, estimates how many remaining payrolls would fall on that same day each month in the year, adjusted for holiday/weekend movement.

## Example

To create a Custom Pay Schedule, you can use the following API request:

```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 '{
        "business_entity_id": "<nmbr_ulid>",
        "title": "Pay Schedule",
        "pay_frequency": "custom"
    }'
```

To create a Payroll on a Custom Pay Schedule, you can use the following API request:

```bash theme={null}
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/payrolls \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "pay_schedule_id": "<nmbr_ulid>",
  "type": "regular",
  "period_start": "2025-05-01",
  "period_end": "2025-05-10",
  "custom_pay_frequency": "semi-monthly",
  "original_pay_date": "2025-05-10"
}'
```