Skip to main content
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.
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: 
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: 
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"
}'