Managing Pay Schedules

​

Overview

• Weekly
• Bi-weekly
• Semi-monthly
• Monthly

​

Pay Schedule Parameters

​

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.

​

Non-Standard Period Counts

​

Custom Pay Schedules

​

Creating a Pay Schedule

​

Endpoint

​

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:56.000000Z",
    "updated_at": "2025-12-11T17:16:56.000000Z"
  },
  "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, paid on fixed pay dates set by day_1 and day_2.
• day_1 and day_2 are any two different days of the month, from 1 to 31, or -1 for the last day of the month. The two days can be in either order.
• day_1 and day_2 can’t both be 28 or later (-1 counts as 31), because those days land on the same date in February.
• If day_1 or day_2 doesn’t exist in a shorter month, the payroll’s original_pay_date is that month’s last day. For example, a pay day of 30 gives an original_pay_date of February 28 in a non-leap year.
• anchor_pay_date must fall on day_1 or day_2. In a month where the pay day doesn’t exist, the month’s last day counts as the pay day.
• The anchor dates set which pay period each pay date pays, so a schedule can pay after a pay period closes or before it closes. For example, a schedule with pay days 7 and 22 and an anchor_end_of_pay_period of January 15 pays the January 1 to 15 pay period on January 22 when anchor_pay_date is January 22, or on January 7 when anchor_pay_date is January 7.

​

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