Skip to main content
Nmbr enables automatic deduction handling on Pay Stubs for Employees. Some deductions are processed directly within the payroll and subsequently disbursed to the appropriate recipients. Others, while deducted during the payroll process, must be remitted by the Employer to the designated recipients. Below is a list of deductions Nmbr can calculate. Statutory withholdings are calculated by Nmbr and need no configuration. See Statutory Withholdings. Benefit contributions are configured separately. See Configuring Benefits. The rest of this guide covers the Deductions you configure yourself: union dues, garnishments, charitable donations, and anything else withheld from an employee’s pay and remitted to a third party.

​
Configuring a Deduction

A Deduction is a recurring instruction attached to a work assignment. During the effective dates, Nmbr applies it to the payroll as a Deduction Line Item.
  • Deductions can be a fixed amount, an amount per hour worked, or a percentage of income.
  • Deductions can be inherited from a Business Preset, allowing for consistent configuration across multiple work assignments.
  • Deductions apply to Employee work assignments. They are not available on contractor work assignments.

​
Key Fields

For the complete list of accepted fields, see the Create a Deduction API reference.

​
Amount Types

amount carries the value and amount_type says how to read it.
  • fixed: amount is a dollar figure, up to 99999.
  • fixed_per_hour: amount is a dollar figure per hour. Nmbr multiplies it by the total hours on the pay stub’s earning line items.
  • percent: amount is a percentage between 0 and 100, applied to the income for the pay period.
A percentage deduction is the one that needs configuring. The rest of this guide is about how Nmbr decides what that percentage applies to.

​
Defining Income for Percentage Deductions

income_basis selects the line items on the pay stub that make up income. Two lists adjust the result: income_includes adds specific subtypes on top of the basis. Each entry names a type (earning, allowance, reimbursement, or employer_benefit) and a subtype. Employer benefit contributions are only ever income when you name them here; no income_basis value includes them. income_subtractions takes specific subtypes back off. Each entry names a type (deduction or employee_benefit) and a subtype. Use it when a deduction is calculated on income after another withholding has already been taken, such as union dues charged on earnings net of an RRSP contribution.
That definition of income is salary, wages, and commission, less the employee’s RRSP contribution on the same pay stub. Income is measured on the pay stub being calculated, not year to date.

​
Gross and Net Income

income_statutory_withholdings decides whether statutory withholdings come off the income before the percentage is applied.
  • none (the default): the percentage applies to the income as defined above. This is a deduction on gross income.
  • all: Nmbr subtracts every statutory withholding on the pay stub (CPP or QPP, EI, QPIP, and income tax) and applies the percentage to what’s left. This is a deduction on net income.
all subtracts the full statutory withholding figure even when your definition of income is narrower than the earnings those withholdings were calculated on. If income is defined as 10,000ofearningsbutthepaystubalsocarries10,000 of earnings but the pay stub also carries 20,000 of allowances, the withholdings subtracted were calculated on the full $30,000. Where that takes income to zero or below, the deduction is zero for the period. Nmbr handles the calculation ordering for you. Gross-income deductions are calculated before statutory withholdings, and net-income deductions after, so a deduction that reduces taxable income and a deduction that depends on the resulting tax can both sit on the same pay stub.

​
Pre-Tax and Post-Tax Deductions

Whether a deduction reduces the tax withheld comes from deduction_type, not from income_statutory_withholdings. The two are independent choices.
  • union_dues reduces the income tax withheld, everywhere except Quebec, and reports in T4 box 44.
  • union_dues_post_tax does not reduce the income tax withheld.
  • charitable_donation does not reduce the income tax withheld, and reports in T4 box 46 and RL-1 box N.
  • garnishment_order and other_deduction do not reduce the income tax withheld.
To check the treatment of any type against a jurisdiction, query the deduction types with the features parameter. See Line Item Type Features.

​
Exemptions

Two fields exempt part of the income before the percentage is applied. Both are optional and both are read only for percentage deductions.
  • income_exemption_amount: a dollar amount, up to 99999.
  • income_exemption_percent: a percentage of income, between 0 and 100.
Set both and Nmbr exempts the greater of the two. A deduction that exempts $700 or 80% of income, on a pay stub where 80% of income is $800, exempts $800. Where the exemption covers the whole income, the deduction is zero for the period. Exemptions apply after income_statutory_withholdings, so a percentage exemption on a net-income deduction is a percentage of income after statutory withholdings. The full order for a percentage deduction:
  1. Total the line items selected by income_basis and income_includes.
  2. Subtract the line items named in income_subtractions.
  3. Subtract statutory withholdings, if income_statutory_withholdings is all.
  4. Subtract the exemption, taking the greater of the dollar and percentage figures.
  5. Apply amount as a percentage of what remains.

​
Frequency and Allocation

frequency decides how often a deduction reaches a pay stub. Deductions are applied to the next regular draft payroll that falls inside the effective window.
  • once: applied to the next payroll, then not repeated once that payroll is no longer a draft.
  • per_payroll: the full amount on every payroll in the effective window.
  • per_month: the amount is divided across the selected payrolls in each calendar month.
per_month requires an amount_type of fixed. Percentage and per-hour deductions recalculate against each period’s earnings, so they apply to every paycheque regardless of frequency. Two fields shape a per_month allocation. date_basis decides which calendar month a payroll belongs to: by_period_start_date (the default), by_period_end_date, or by_pay_date. pay_period_cadence lists the pay periods in the month that receive a share, as 1-based positions. -1 means the final period of the month. When omitted, every period in the month receives a share. A 200monthlydeductiononabi−weeklyschedulewitha‘payperiodcadence‘of‘[1]‘takesthefull200 monthly deduction on a bi-weekly schedule with a `pay_period_cadence` of `[1]` takes the full 200 on the first payroll of the month, and nothing on the rest. If a selected position doesn’t exist in a given month, its share is redistributed across the remaining selected periods. Both fields are read only for per_month fixed-amount deductions. Sending either one on any other deduction returns a validation error instead of storing a value that would never be used.

​
Validations

  • amount must be between 0 and 100 when amount_type is percent, and between 0 and 99999 for the other types.
  • A deduction must include a deduction_type unless inherited from a Business Preset.
  • frequency may only be per_month when amount_type is fixed.
  • date_basis and pay_period_cadence may only be set on per_month fixed-amount deductions.
  • effective_to must be on or after effective_from.
  • Every subtype named in income_includes and income_subtractions must be a valid subtype of its type.
  • The work assignment must belong to an Employee.

​
Deduction Line Items

Deduction Line Items represent the amounts actually withheld during payroll processing. Nmbr generates them from the configured Deductions, and you can create them directly for one-off withholdings. Updating, ending, and deleting a Deduction is forward-looking. See Updating, ending, and deleting.

​
Deduction Types

Retrieve the supported types with GET /deduction_types. Each deduction type object includes:
  • type: the unique identifier used in the API, e.g. union_dues, garnishment_order.
  • label: a human-readable name for display purposes, e.g. “Union Dues”, “Garnishment Order”.
See the List Deduction Types API reference.

​
Example Scenarios

​
Union dues as a percentage of gross earnings

Dues of 1.5% of all earnings, deducted every payroll and remitted to the union:

​
Union dues per hour worked

Dues of $0.45 for every hour on the pay stub:

​
Garnishment on net pay with a protected minimum

A garnishment order takes 30% of the employee’s pay after statutory withholdings, and the first $800 of that income each period is protected:
On a pay stub with $4,000 of total income and $1,200 of statutory withholdings, income is $2,800. The $800 exemption leaves $2,000, and the deduction is $600.

​
Charitable donation on earnings net of an RRSP contribution

A 2% donation calculated on salary and wages after the employee’s RRSP contribution has been taken:

​
Fixed monthly deduction on the first payroll of the month

A $50 monthly deduction, taken in full on the first payroll of each calendar month: