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.

​

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