curl --request POST \
--url https://sandbox.nmbr.co/services/payroll/deductions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"work_assignment_id": "<id>",
"deduction_type": "income_tax",
"frequency": "per_month",
"amount": "35",
"amount_type": "fixed",
"hours_basis": "all_earnings",
"max_lifetime_deduction": "1200",
"income_basis": "all_earnings",
"income_statutory_withholdings": "none",
"effective_from": "2026-01-01",
"tag_assignment": {
"unit": "percentage",
"tag_allocations": [
{
"tags": [
"<id>"
],
"value": 100
}
]
}
}
'import requests
url = "https://sandbox.nmbr.co/services/payroll/deductions"
payload = {
"work_assignment_id": "<id>",
"deduction_type": "income_tax",
"frequency": "per_month",
"amount": "35",
"amount_type": "fixed",
"hours_basis": "all_earnings",
"max_lifetime_deduction": "1200",
"income_basis": "all_earnings",
"income_statutory_withholdings": "none",
"effective_from": "2026-01-01",
"tag_assignment": {
"unit": "percentage",
"tag_allocations": [
{
"tags": ["<id>"],
"value": 100
}
]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
work_assignment_id: '<id>',
deduction_type: 'income_tax',
frequency: 'per_month',
amount: '35',
amount_type: 'fixed',
hours_basis: 'all_earnings',
max_lifetime_deduction: '1200',
income_basis: 'all_earnings',
income_statutory_withholdings: 'none',
effective_from: '2026-01-01',
tag_assignment: {unit: 'percentage', tag_allocations: [{tags: ['<id>'], value: 100}]}
})
};
fetch('https://sandbox.nmbr.co/services/payroll/deductions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.nmbr.co/services/payroll/deductions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'work_assignment_id' => '<id>',
'deduction_type' => 'income_tax',
'frequency' => 'per_month',
'amount' => '35',
'amount_type' => 'fixed',
'hours_basis' => 'all_earnings',
'max_lifetime_deduction' => '1200',
'income_basis' => 'all_earnings',
'income_statutory_withholdings' => 'none',
'effective_from' => '2026-01-01',
'tag_assignment' => [
'unit' => 'percentage',
'tag_allocations' => [
[
'tags' => [
'<id>'
],
'value' => 100
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.nmbr.co/services/payroll/deductions"
payload := strings.NewReader("{\n \"work_assignment_id\": \"<id>\",\n \"deduction_type\": \"income_tax\",\n \"frequency\": \"per_month\",\n \"amount\": \"35\",\n \"amount_type\": \"fixed\",\n \"hours_basis\": \"all_earnings\",\n \"max_lifetime_deduction\": \"1200\",\n \"income_basis\": \"all_earnings\",\n \"income_statutory_withholdings\": \"none\",\n \"effective_from\": \"2026-01-01\",\n \"tag_assignment\": {\n \"unit\": \"percentage\",\n \"tag_allocations\": [\n {\n \"tags\": [\n \"<id>\"\n ],\n \"value\": 100\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.nmbr.co/services/payroll/deductions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"work_assignment_id\": \"<id>\",\n \"deduction_type\": \"income_tax\",\n \"frequency\": \"per_month\",\n \"amount\": \"35\",\n \"amount_type\": \"fixed\",\n \"hours_basis\": \"all_earnings\",\n \"max_lifetime_deduction\": \"1200\",\n \"income_basis\": \"all_earnings\",\n \"income_statutory_withholdings\": \"none\",\n \"effective_from\": \"2026-01-01\",\n \"tag_assignment\": {\n \"unit\": \"percentage\",\n \"tag_allocations\": [\n {\n \"tags\": [\n \"<id>\"\n ],\n \"value\": 100\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.nmbr.co/services/payroll/deductions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"work_assignment_id\": \"<id>\",\n \"deduction_type\": \"income_tax\",\n \"frequency\": \"per_month\",\n \"amount\": \"35\",\n \"amount_type\": \"fixed\",\n \"hours_basis\": \"all_earnings\",\n \"max_lifetime_deduction\": \"1200\",\n \"income_basis\": \"all_earnings\",\n \"income_statutory_withholdings\": \"none\",\n \"effective_from\": \"2026-01-01\",\n \"tag_assignment\": {\n \"unit\": \"percentage\",\n \"tag_allocations\": [\n {\n \"tags\": [\n \"<id>\"\n ],\n \"value\": 100\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<id>",
"object": "deduction",
"data": {
"work_assignment": {
"id": "<id>",
"object": "work_assignment",
"links": {
"self": "/work_assignments/<id>"
}
},
"frequency": "per_month",
"date_basis": "by_period_start_date",
"pay_period_cadence": [
1
],
"deduction_type": {
"id": "<id>",
"object": "deduction_type",
"data": {
"type": "income_tax",
"label": "Income tax debt",
"locale": "en"
},
"links": {
"self": "/deduction_types/income_tax"
}
},
"amount": 35,
"amount_type": "fixed",
"hours_basis": "all_earnings",
"hours_includes": [],
"max_lifetime_deduction": 1200,
"income_basis": "all_earnings",
"income_includes": [],
"income_subtractions": [],
"income_statutory_withholdings": "none",
"income_exemption_amount": null,
"income_exemption_percent": null,
"effective_from": "2026-01-01",
"effective_to": null,
"title": null,
"title_translations": null,
"title_translated": null,
"remittance_account": null,
"business_preset": null,
"expense_accounting_code": null,
"liability_accounting_code": null,
"external_ref": null,
"created_at": "2026-01-01T00:00:00.000000Z",
"updated_at": "2026-01-01T00:00:00.000000Z"
},
"links": {
"self": "/deductions/<id>"
}
}Create a deduction
curl --request POST \
--url https://sandbox.nmbr.co/services/payroll/deductions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"work_assignment_id": "<id>",
"deduction_type": "income_tax",
"frequency": "per_month",
"amount": "35",
"amount_type": "fixed",
"hours_basis": "all_earnings",
"max_lifetime_deduction": "1200",
"income_basis": "all_earnings",
"income_statutory_withholdings": "none",
"effective_from": "2026-01-01",
"tag_assignment": {
"unit": "percentage",
"tag_allocations": [
{
"tags": [
"<id>"
],
"value": 100
}
]
}
}
'import requests
url = "https://sandbox.nmbr.co/services/payroll/deductions"
payload = {
"work_assignment_id": "<id>",
"deduction_type": "income_tax",
"frequency": "per_month",
"amount": "35",
"amount_type": "fixed",
"hours_basis": "all_earnings",
"max_lifetime_deduction": "1200",
"income_basis": "all_earnings",
"income_statutory_withholdings": "none",
"effective_from": "2026-01-01",
"tag_assignment": {
"unit": "percentage",
"tag_allocations": [
{
"tags": ["<id>"],
"value": 100
}
]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
work_assignment_id: '<id>',
deduction_type: 'income_tax',
frequency: 'per_month',
amount: '35',
amount_type: 'fixed',
hours_basis: 'all_earnings',
max_lifetime_deduction: '1200',
income_basis: 'all_earnings',
income_statutory_withholdings: 'none',
effective_from: '2026-01-01',
tag_assignment: {unit: 'percentage', tag_allocations: [{tags: ['<id>'], value: 100}]}
})
};
fetch('https://sandbox.nmbr.co/services/payroll/deductions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.nmbr.co/services/payroll/deductions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'work_assignment_id' => '<id>',
'deduction_type' => 'income_tax',
'frequency' => 'per_month',
'amount' => '35',
'amount_type' => 'fixed',
'hours_basis' => 'all_earnings',
'max_lifetime_deduction' => '1200',
'income_basis' => 'all_earnings',
'income_statutory_withholdings' => 'none',
'effective_from' => '2026-01-01',
'tag_assignment' => [
'unit' => 'percentage',
'tag_allocations' => [
[
'tags' => [
'<id>'
],
'value' => 100
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.nmbr.co/services/payroll/deductions"
payload := strings.NewReader("{\n \"work_assignment_id\": \"<id>\",\n \"deduction_type\": \"income_tax\",\n \"frequency\": \"per_month\",\n \"amount\": \"35\",\n \"amount_type\": \"fixed\",\n \"hours_basis\": \"all_earnings\",\n \"max_lifetime_deduction\": \"1200\",\n \"income_basis\": \"all_earnings\",\n \"income_statutory_withholdings\": \"none\",\n \"effective_from\": \"2026-01-01\",\n \"tag_assignment\": {\n \"unit\": \"percentage\",\n \"tag_allocations\": [\n {\n \"tags\": [\n \"<id>\"\n ],\n \"value\": 100\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.nmbr.co/services/payroll/deductions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"work_assignment_id\": \"<id>\",\n \"deduction_type\": \"income_tax\",\n \"frequency\": \"per_month\",\n \"amount\": \"35\",\n \"amount_type\": \"fixed\",\n \"hours_basis\": \"all_earnings\",\n \"max_lifetime_deduction\": \"1200\",\n \"income_basis\": \"all_earnings\",\n \"income_statutory_withholdings\": \"none\",\n \"effective_from\": \"2026-01-01\",\n \"tag_assignment\": {\n \"unit\": \"percentage\",\n \"tag_allocations\": [\n {\n \"tags\": [\n \"<id>\"\n ],\n \"value\": 100\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.nmbr.co/services/payroll/deductions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"work_assignment_id\": \"<id>\",\n \"deduction_type\": \"income_tax\",\n \"frequency\": \"per_month\",\n \"amount\": \"35\",\n \"amount_type\": \"fixed\",\n \"hours_basis\": \"all_earnings\",\n \"max_lifetime_deduction\": \"1200\",\n \"income_basis\": \"all_earnings\",\n \"income_statutory_withholdings\": \"none\",\n \"effective_from\": \"2026-01-01\",\n \"tag_assignment\": {\n \"unit\": \"percentage\",\n \"tag_allocations\": [\n {\n \"tags\": [\n \"<id>\"\n ],\n \"value\": 100\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<id>",
"object": "deduction",
"data": {
"work_assignment": {
"id": "<id>",
"object": "work_assignment",
"links": {
"self": "/work_assignments/<id>"
}
},
"frequency": "per_month",
"date_basis": "by_period_start_date",
"pay_period_cadence": [
1
],
"deduction_type": {
"id": "<id>",
"object": "deduction_type",
"data": {
"type": "income_tax",
"label": "Income tax debt",
"locale": "en"
},
"links": {
"self": "/deduction_types/income_tax"
}
},
"amount": 35,
"amount_type": "fixed",
"hours_basis": "all_earnings",
"hours_includes": [],
"max_lifetime_deduction": 1200,
"income_basis": "all_earnings",
"income_includes": [],
"income_subtractions": [],
"income_statutory_withholdings": "none",
"income_exemption_amount": null,
"income_exemption_percent": null,
"effective_from": "2026-01-01",
"effective_to": null,
"title": null,
"title_translations": null,
"title_translated": null,
"remittance_account": null,
"business_preset": null,
"expense_accounting_code": null,
"liability_accounting_code": null,
"external_ref": null,
"created_at": "2026-01-01T00:00:00.000000Z",
"updated_at": "2026-01-01T00:00:00.000000Z"
},
"links": {
"self": "/deductions/<id>"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Must belong to a work assignment associated with an entity of type Employee.
The frequency at which this deduction is applied to Pay Stubs. When per_month, the amount is distributed across selected Payrolls in the calendar month. per_month is only valid when amount_type is fixed; percent and per-hour deductions apply to every paycheque regardless of frequency.
once, per_month, per_payroll The deduction amount per occurrence. When amount_type is percent, this is interpreted as a percentage of the income basis. When fixed_per_hour, it is multiplied by the hours on the Pay Stub's earning line items selected by hours_basis and hours_includes. Otherwise it is a fixed dollar amount.
Up to 2 decimal places.
x >= 0Must be a multiple of 0.01Whether amount is a fixed dollar value (fixed), a dollar value per hour worked (fixed_per_hour), or a percentage of the income basis (percent).
fixed, fixed_per_hour, percent The date from which this deduction is applied to Pay Stubs.
The type of deduction, which determines how it is categorized and remitted.
Must be present when business_preset_id is either empty or not set.
charitable_donation, garnishment_order, income_tax, other_deduction, union_dues, union_dues_post_tax 255Which earnings' hours a fixed_per_hour deduction multiplies amount by. all_earnings includes the hours on all earnings. regular_earnings includes only the hours on salary and wage earnings. none doesn't include any earnings, and can be used with hours_includes to count only the hours on specific earnings. Defaults to all_earnings, and can only be changed when amount_type is fixed_per_hour.
all_earnings, none, regular_earnings An optional list of earnings whose hours are counted in addition to those included via hours_basis. Each entry has a type of earning and a subtype. Can only be changed when amount_type is fixed_per_hour.
The most this deduction will ever deduct, such as the balance owed on a loan or advance. Once the amounts it deducted on approved payrolls reach this maximum, it stops deducting, and the Pay Stub that reaches it deducts only the remainder. Amounts repaid before the deduction was created aren't counted, so set it to the balance still owed when creating the deduction. Changing it later changes the total, not the remaining balance: amounts already deducted still count toward it. null if there is no maximum.
Up to 2 decimal places.
0 <= x <= 999999Must be a multiple of 0.01Determines the income used as the base for percentage-based deductions. regular_earnings includes only salary and wage earnings. all_earnings includes all earnings. total_income includes all earnings, taxable allowances, and taxable reimbursements. none doesn't include any line items, and can be used with income_includes for completely custom definitions of income.
all_earnings, none, regular_earnings, total_income An optional list of specific earnings, allowances, and other line item types to include in the income calculation in addition to those included via income_basis.
Whether to subtract statutory withholdings (CPP, EI, income tax) from the income before the deduction amount is calculated.
all, none A fixed dollar amount to exempt from the income before calculating the deduction.
Up to 2 decimal places.
0 <= x <= 99999Must be a multiple of 0.01A percentage of the income to exempt before calculating the deduction amount.
Up to 2 decimal places.
0 <= x <= 100Must be a multiple of 0.01The date after which this deduction is no longer applied. null if the deduction applies indefinitely.
The remittance account to which collected deduction amounts are remitted.
255Up to 4 decimal places.
Hide child attributes
Hide child attributes
percentage Which payroll date determines the calendar month for the allocation. Applies only to fixed-amount per_month deductions.
by_pay_date, by_period_end_date, by_period_start_date Which pay periods within the month receive the allocation. An array of 1-based positions; -1 is the final period. Applies only to fixed-amount per_month deductions.
1Response
Created
The unique identifier of the object in Nmbr.
The type of the object in Nmbr ("deduction").
Hide child attributes
Hide child attributes
The frequency at which this deduction is applied to Pay Stubs. When per_month, the amount is distributed across selected Payrolls in the calendar month. per_month is only valid when amount_type is fixed; percent and per-hour deductions apply to every paycheque regardless of frequency.
once, per_month, per_payroll Which payroll date determines the calendar month for the allocation. Applies only to fixed-amount per_month deductions.
by_pay_date, by_period_end_date, by_period_start_date Which pay periods within the month receive the allocation. An array of 1-based positions; -1 is the final period. Applies only to fixed-amount per_month deductions.
The type of deduction, which determines how it is categorized and remitted.
Hide child attributes
Hide child attributes
The unique identifier of the object in Nmbr.
The type of the object in Nmbr ("deduction_type").
Hide child attributes
Hide child attributes
The string identifier for this deduction type.
The human-readable display name for this deduction type.
Hide child attributes
Hide child attributes
The payroll calculation this entry describes.
eht, grossable, income_tax, insurable, money_moving, pensionable, stat_payable, vacationable, wcb Human-readable name for the payroll calculation.
How this type affects the calculation, broken down by jurisdiction. Jurisdictions where it does not apply are omitted.
Hide child attributes
Hide child attributes
The jurisdiction this applies to (e.g. ca_federal, ca_on, ca_qc).
How this type affects the payroll calculation in this jurisdiction.
accrues_vacation_pay, included_in_gross_pay, included_in_stat_holiday_pay, moves_money, reduces_base, tax_credit, withholding Plain-language explanation of how this type affects the calculation in this jurisdiction.
The program that applies in this jurisdiction, for calculations that use different programs by jurisdiction (e.g. CPP federally, QPP in Quebec; EI federally, QPIP in Quebec).
Hide child attributes
Hide child attributes
The form code (e.g. t4).
Human-readable form name.
The boxes on the form this type contributes to in at least one province.
Hide child attributes
Hide child attributes
The box or line identifier on the form.
Plain-language explanation of the box, when available.
The provinces of employment where amounts of this type are reported in this box. RL-1 boxes apply only in Quebec. Most T4 and T4A boxes apply in every province; a few, such as for Quebec tips, do not.
The province of employment (e.g. ca_on, ca_qc).
The deduction amount per occurrence. When amount_type is percent, this is interpreted as a percentage of the income basis. When fixed_per_hour, it is multiplied by the hours on the Pay Stub's earning line items selected by hours_basis and hours_includes. Otherwise it is a fixed dollar amount.
Whether amount is a fixed dollar value (fixed), a dollar value per hour worked (fixed_per_hour), or a percentage of the income basis (percent).
fixed, fixed_per_hour, percent Which earnings' hours a fixed_per_hour deduction multiplies amount by. all_earnings includes the hours on all earnings. regular_earnings includes only the hours on salary and wage earnings. none doesn't include any earnings, and can be used with hours_includes to count only the hours on specific earnings. Defaults to all_earnings, and can only be changed when amount_type is fixed_per_hour.
all_earnings, none, regular_earnings An optional list of earnings whose hours are counted in addition to those included via hours_basis. Each entry has a type of earning and a subtype. Can only be changed when amount_type is fixed_per_hour.
The most this deduction will ever deduct, such as the balance owed on a loan or advance. Once the amounts it deducted on approved payrolls reach this maximum, it stops deducting, and the Pay Stub that reaches it deducts only the remainder. Amounts repaid before the deduction was created aren't counted, so set it to the balance still owed when creating the deduction. Changing it later changes the total, not the remaining balance: amounts already deducted still count toward it. null if there is no maximum.
Determines the income used as the base for percentage-based deductions. regular_earnings includes only salary and wage earnings. all_earnings includes all earnings. total_income includes all earnings, taxable allowances, and taxable reimbursements. none doesn't include any line items, and can be used with income_includes for completely custom definitions of income.
all_earnings, none, regular_earnings, total_income An optional list of specific earnings, allowances, and other line item types to include in the income calculation in addition to those included via income_basis.
An optional list of deductions and employee benefits to subtract from the income before the deduction amount is calculated.
Whether to subtract statutory withholdings (CPP, EI, income tax) from the income before the deduction amount is calculated.
all, none A fixed dollar amount to exempt from the income before calculating the deduction.
A percentage of the income to exempt before calculating the deduction amount.
The date from which this deduction is applied to Pay Stubs.
The date after which this deduction is no longer applied. null if the deduction applies indefinitely.
255The translation of the title property for the request locale. Computed using the values in title and title_translations and the value of the request's Accept-Language header.
A reference to the object in an external system, e.g. the primary key of the object in your application's database. Nmbr doesn't use, validate, parse, or require this value to be unique - it simply stores it for your reference.
255The date and time the object was created in Nmbr.
The date and time the object was last updated in Nmbr.