Skip to main content
Paying out earnings to employees is one of the primary functions of payroll software. Depending on the province or territory of employment, different labour laws apply relating to minimum wage and vacation earnings. Some common types of earnings include:
  • Salary or Wage
  • Bonuses
  • Commissions
  • Vacation Pay
  • Severance Pay
  • Overtime

​
Pay Rates and Recurring Earnings

Nmbr has two features that can automatically create earning line items on payrolls:
  1. Pay Rates
  2. Recurring Earnings (“Other Earnings” in the Nmbr component)
The biggest difference between the two is that Pay Rates do math and Recurring Earnings don’t. Pay Rates create an earning line item whose amount may be prorated or based on the number of hours entered in each pay period. Recurring Earnings create an earning line item with a fixed amount on every payroll they’re effective on. A smaller difference is that Pay Rates and Recurring Earnings support different earning types. Pay Rates only support salary and hourly earning types, while Recurring Earnings support all earning types except for salary. Otherwise, the two features are interchangeable. We recommend using Pay Rates for most employment earnings (salaries and hourly wages) and Recurring Earnings for other types of earnings (e.g. parental top-ups, commissions, etc).

​
Pay Rates

Having one or more Pay Rates on a Work Assignment simplifies the task of managing earnings for an Employee. Nmbr uses the Pay Rates to automatically add Earning Line Items to the next Payroll.

​
Annual Salary

For Pay Rates with a type of salary, the Earning Line Item will have the earning amount set based on the Pay Schedules frequency - e.g for a semi-monthly Pay Schedule, the Pay Rate rate will be divided evenly across 24 payrolls. If the Pay Rate begins in the middle of a Payroll’s earning period, that Payroll will be prorated for that period. The prorated amount is calculated using 260 working days in a year. If you wish to override the amount on a specific Salary Earning Line Item, you should set the custom_amount field on the Line Item.

​
Hourly Wage

For Pay Rates with a type of hourly, the Earning Line Item will be created with an empty amount. Nmbr will automatically calculate the correct amount once the hours field has been set on that Line Item. The amount is calculated using the Pay Rate for that Line Item. If you wish to override the amount on a specific Wage Earning Line Item, you should set the custom_amount field on the Line Item.

​
Examples

You can create a Pay Rate for an employee using the pay_rates endpoint: Request 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/pay_rates \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "title": "Location Manager",
        "type": "salary",
        "rate": "60000",
        "expected_hours_per_week": "38",
        "effective_from": "2023-11-01T00:00:00.000000Z",
        "work_assignment_id": "01hhcy3hg60x3dq8hfj31hgyea",
    }'
📘 Supporting multiple pay rates Nmbr gives you the ability to add multiple pay rates for a single Work Assignments. Scheduling and time and attendance software can leverage this feature to ensure employees are paid for the right roles and shifts.
Once a payroll has been approved, Nmbr will automatically calculate the correct periodic earnings for the next payroll based on the Pay Schedule frequency.

​
Overtime Rates

In many workplaces, employees may have one or more overtime rates assigned to them. You can use the Nmbr API Overtime Rates to simplify creating, managing and calculating the correct overtime earnings for Employees. Both salary and wage Pay Rates can have one or more Overtime Rates assigned to them. When creating an Overtime Rate, you only need to provide the Pay Rate and rate_multiplier, and Nmbr will calculate the expected hourly_rate. For Pay Rates with a type of salary, the hourly rate is calculated using the expected_hours_per_week in a work year of 260 days. If you wish to override the calculated hourly_rate, you may set the hourly_rate_override. To add an Overtime to a Pay stub, create an Earning Line Item with an earning_type of overtime, and with an overtime_rate_id. Nmbr will then use the hours to calculate the correct earning amount for that Line Item.

​
Example

Creating an Overtime Rate 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/overtime_items \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "pay_rate_id": "01hhcy3j61408834dmfe8bzg24",
        "rate_multiplier": 1.5
     }'
Creating an Overtime Earning Line Item 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/earning_line_items \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "pay_stub_id": "<ulid>",
        "overtime_rate_id": "01j9m00375ea5mzbzgpx6a8yqf",
        "hours": 20,
        "earning_type": "overtime"
     }'

​
Ending Pay Rates

All recurrence types, including pay rates, have an effective window defined by their effective_from and effective_to fields. If a pay period starts in this window, a managed line item will be created on the work assignment’s pay stub automatically. However, unlike other recurrence types, pay rates allow you to create custom line items that refer to the pay rate and use it to calculate the amount from the hours at that rate. The pay rate’s effective window affects custom line items in 2 ways:
  1. In order to create a custom line item referring to a pay rate, the pay period must start in the pay rate’s effective window. If it doesn’t, the request to create the line item will be rejected.
  2. When a pay rate’s effective_to field is set (i.e. when the pay rate is ended), any line items in pay periods after that date will be deleted automatically.

​
Example

An employer has an employee working as an Apprentice Electrician 3. The employee plans to take a week of vacation 6 months from now. The employer records the planned vacation by creating a vacation pay line item for 40 hours at the employee’s pay rate in the payroll 6 months from now. However, 3 months from now the employee starts a new term as an Apprentice Electrician 4. The employer ends the employee’s old pay rate and creates a new pay rate. When this happens, the vacation pay earning line item will be deleted, as it refers to a pay rate that is no longer effective. The employer will need to create a new vacation pay line item at the new rate.

​
Recurring Earnings (“Other Earnings”)

Recurring Earnings simply create an earning line item with a fixed amount on every payroll they’re effective on. If you create a recurring earning, the recurring earning will create an earning line item on each payroll with that fixed amount.
  • The line item’s amount will not be prorated in any way.
  • The line item’s amount will not be tied to its hours. If you set the hours on the line item, its amount will not be recalculated, as there is no underlying rate to recalculate it with. The hours will appear on the pay stub, however, if set.