Skip to main content

​
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

FieldTypeRequiredDescription
titlestringYesThe label used for this Pay Schedule.
pay_frequencyenumYesMust be one of weekly, bi-weekly, semi-monthly, monthly or custom.
anchor_pay_dateISO8601 date (YYYY-MM-DD)YesFirst intended pay date (before weekend/holiday movement).
anchor_end_of_pay_periodISO8601 date (YYYY-MM-DD)YesFinal day of the first earning period.
day_1integerConditionalOn monthly or semi-monthly schedules, the numeric day of month for the first payroll.
day_2integerConditionalOn semi-monthly, the numeric day in the month for the second payroll.
pay_day_movement_settingenumNoDetermines how pay dates are adjusted for holidays or weekends. Defaults to inherit.
generate_payrolls_fromISO8601 date (YYYY-MM-DD)NoAvailable 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 guide.

​
Creating a Pay Schedule

​
Endpoint

POST /services/payroll/pay_schedules

​
Request Example

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

{
  "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

{
    "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.