> ## Documentation Index > Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt > Use this file to discover all available pages before exploring further. # Set up Pay Rates and Recurring Earnings 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. `expected_hours_per_week` is required when you create a Pay Rate of either `type`, but Nmbr only uses it for `salary` rates. On a `salary` rate it sets the default hours on the earning line item and derives the equivalent hourly rate used for proration and Overtime Rates. On an `hourly` rate it has no effect: the earning `amount` is the `hours` you enter times the hourly `rate`, and it is not used as the line item's `hours`. 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** ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/pay_rates \ --header 'Authorization: Bearer ' \ --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" }' ```
View sample JSON Response ```json theme={null} { "id": "01hhcy3j61408834dmfe8bzg24", "object": "pay_rate", "data": { "title": "Location Manager", "type": "salary", "rate": "60000", "expected_hours_per_week": "38.00", "effective_from": "2023-11-01T00:00:00.000000Z", "effective_to": null, "created_at": "2023-12-11T17:16:58.000000Z", "updated_at": "2023-12-11T17:16:58.000000Z" }, "links": { "self": "https://sandbox.nmbr.co/services/payroll/pay_rates/01hhcy3j61408834dmfe8bzg24" } } ```
> 📘 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 ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/overtime_rates \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "pay_rate_id": "01hhcy3j61408834dmfe8bzg24", "rate_multiplier": 1.5 }' ```
View sample JSON Response ```json theme={null} { "id": "01j9m00375ea5mzbzgpx6a8yqf", "object": "overtime_rate", "data": { "pay_rate": { "id": "01hhcy3j61408834dmfe8bzg24", "object": "pay_rate", "links": { "self": "https://sandbox.nmbr.co/services/payroll/pay_rates/01hhcy3j61408834dmfe8bzg24" } }, "title": "1.5x", "rate_multiplier": 1.5, "hourly_rate": 43.28, "hourly_rate_override": null, "archived_at": null, "is_editable": true, "is_deletable": true, "created_at": "2024-10-07T17:21:26.000000Z", "updated_at": "2024-10-07T17:21:26.000000Z" }, "links": { "self": "https://sandbox.nmbr.co/services/payroll/overtime_rates/01j9m00375ea5mzbzgpx6a8yqf" } } ```
Creating an Overtime Earning Line Item ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/earning_line_items \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "pay_stub_id": "", "overtime_rate_id": "01j9m00375ea5mzbzgpx6a8yqf", "hours": 20, "earning_type": "overtime" }' ```
View sample JSON Response ```json theme={null} { "id": "01j9m0cb7taf2jr460dr7kfddp", "object": "earning_line_item", "data": { "pay_stub": { "id": "01j9chznfxy478d52d69eqnhd3", "object": "pay_stub", "links": { "self": "https://sandbox.nmbr.co/services/payroll/pay_stubs/01j9chznfxy478d52d69eqnhd3" } }, "amount": 865.6, "is_managed": false, "managed_amount": null, "custom_amount": 865.6, "line_item_type": "earning", "earning_type": { "id": "01J9CHYSP5DJK15NBFADAH4HNT", "object": "earning_type", "data": { "type": "overtime", "label": "Overtime", "supported_payroll_types": { "regular": true, "historical": true, "off_cycle": true }, "created_at": "2024-10-04T20:01:23.000000Z", "updated_at": "2024-10-04T20:01:23.000000Z" }, "links": { "self": null } }, "hours": 20, "accrued_vacation_pay": null, "recurrence": { "id": "01hhcy3j61408834dmfe8bzg24", "object": "pay_rate", "links": { "self": "https://sandbox.nmbr.co/services/payroll/pay_rates/01hhcy3j61408834dmfe8bzg24" } }, "overtime_rate": { "id": "01j9m00375ea5mzbzgpx6a8yqf", "object": "overtime_rate", "links": { "self": "https://sandbox.nmbr.co/services/payroll/overtime_rates/01j9m00375ea5mzbzgpx6a8yqf" } }, "title": null, "created_at": "2024-10-07T17:28:08.000000Z", "updated_at": "2024-10-07T17:28:08.000000Z" }, "links": { "self": "https://sandbox.nmbr.co/services/payroll/earning_line_items/01j9m0cb7taf2jr460dr7kfddp" } } ```
### 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.