Create an earning line item

curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/earning_line_items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pay_stub_id": "<id>",
  "earning_type": "wage",
  "custom_amount": "3000",
  "custom_hours": "0",
  "accrued_vacation_pay": "0",
  "title": "Earning",
  "custom_tag_assignment": {
    "unit": "percentage",
    "tag_allocations": [
      {
        "tags": [
          "<id>"
        ],
        "value": 100
      }
    ]
  }
}
'

import requests

url = "https://sandbox.nmbr.co/services/payroll/earning_line_items"

payload = {
    "pay_stub_id": "<id>",
    "earning_type": "wage",
    "custom_amount": "3000",
    "custom_hours": "0",
    "accrued_vacation_pay": "0",
    "title": "Earning",
    "custom_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({
    pay_stub_id: '<id>',
    earning_type: 'wage',
    custom_amount: '3000',
    custom_hours: '0',
    accrued_vacation_pay: '0',
    title: 'Earning',
    custom_tag_assignment: {unit: 'percentage', tag_allocations: [{tags: ['<id>'], value: 100}]}
  })
};

fetch('https://sandbox.nmbr.co/services/payroll/earning_line_items', 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/earning_line_items",
  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([
    'pay_stub_id' => '<id>',
    'earning_type' => 'wage',
    'custom_amount' => '3000',
    'custom_hours' => '0',
    'accrued_vacation_pay' => '0',
    'title' => 'Earning',
    'custom_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/earning_line_items"

	payload := strings.NewReader("{\n  \"pay_stub_id\": \"<id>\",\n  \"earning_type\": \"wage\",\n  \"custom_amount\": \"3000\",\n  \"custom_hours\": \"0\",\n  \"accrued_vacation_pay\": \"0\",\n  \"title\": \"Earning\",\n  \"custom_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/earning_line_items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"pay_stub_id\": \"<id>\",\n  \"earning_type\": \"wage\",\n  \"custom_amount\": \"3000\",\n  \"custom_hours\": \"0\",\n  \"accrued_vacation_pay\": \"0\",\n  \"title\": \"Earning\",\n  \"custom_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/earning_line_items")

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  \"pay_stub_id\": \"<id>\",\n  \"earning_type\": \"wage\",\n  \"custom_amount\": \"3000\",\n  \"custom_hours\": \"0\",\n  \"accrued_vacation_pay\": \"0\",\n  \"title\": \"Earning\",\n  \"custom_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": "earning_line_item",
  "data": {
    "pay_stub": {
      "id": "<id>",
      "object": "pay_stub",
      "links": {
        "self": "/pay_stubs/<id>"
      }
    },
    "amount": 3000,
    "custom_amount": 3000,
    "managed_amount": null,
    "is_managed": false,
    "line_item_type": "earning",
    "earning_type": {
      "id": "<id>",
      "object": "earning_type",
      "data": {
        "type": "wage",
        "label": "Wage",
        "supported_payroll_types": {
          "regular": true,
          "historical": true,
          "off_cycle": true
        }
      },
      "links": {
        "self": "/earning_types/wage"
      }
    },
    "hours": 0,
    "managed_hours": null,
    "custom_hours": 0,
    "accrued_vacation_pay": 0,
    "recurrence": null,
    "pay_rate": null,
    "overtime_rate": null,
    "title": "Earning",
    "title_translations": null,
    "title_translated": "Earning",
    "expense_accounting_code": null,
    "managed_expense_accounting_code": null,
    "custom_expense_accounting_code": null,
    "liability_accounting_code": null,
    "managed_liability_accounting_code": null,
    "custom_liability_accounting_code": null,
    "business_preset": null,
    "source_adjustment": null,
    "component_settings": {
      "attributes_locked": false
    },
    "earned_on": null,
    "managed_earned_on": null,
    "custom_earned_on": null,
    "external_ref": null,
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/earning_line_items/<id>"
  }
}

POST

earning_line_items

Create an earning line item

curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/earning_line_items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pay_stub_id": "<id>",
  "earning_type": "wage",
  "custom_amount": "3000",
  "custom_hours": "0",
  "accrued_vacation_pay": "0",
  "title": "Earning",
  "custom_tag_assignment": {
    "unit": "percentage",
    "tag_allocations": [
      {
        "tags": [
          "<id>"
        ],
        "value": 100
      }
    ]
  }
}
'

import requests

url = "https://sandbox.nmbr.co/services/payroll/earning_line_items"

payload = {
    "pay_stub_id": "<id>",
    "earning_type": "wage",
    "custom_amount": "3000",
    "custom_hours": "0",
    "accrued_vacation_pay": "0",
    "title": "Earning",
    "custom_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({
    pay_stub_id: '<id>',
    earning_type: 'wage',
    custom_amount: '3000',
    custom_hours: '0',
    accrued_vacation_pay: '0',
    title: 'Earning',
    custom_tag_assignment: {unit: 'percentage', tag_allocations: [{tags: ['<id>'], value: 100}]}
  })
};

fetch('https://sandbox.nmbr.co/services/payroll/earning_line_items', 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/earning_line_items",
  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([
    'pay_stub_id' => '<id>',
    'earning_type' => 'wage',
    'custom_amount' => '3000',
    'custom_hours' => '0',
    'accrued_vacation_pay' => '0',
    'title' => 'Earning',
    'custom_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/earning_line_items"

	payload := strings.NewReader("{\n  \"pay_stub_id\": \"<id>\",\n  \"earning_type\": \"wage\",\n  \"custom_amount\": \"3000\",\n  \"custom_hours\": \"0\",\n  \"accrued_vacation_pay\": \"0\",\n  \"title\": \"Earning\",\n  \"custom_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/earning_line_items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"pay_stub_id\": \"<id>\",\n  \"earning_type\": \"wage\",\n  \"custom_amount\": \"3000\",\n  \"custom_hours\": \"0\",\n  \"accrued_vacation_pay\": \"0\",\n  \"title\": \"Earning\",\n  \"custom_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/earning_line_items")

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  \"pay_stub_id\": \"<id>\",\n  \"earning_type\": \"wage\",\n  \"custom_amount\": \"3000\",\n  \"custom_hours\": \"0\",\n  \"accrued_vacation_pay\": \"0\",\n  \"title\": \"Earning\",\n  \"custom_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": "earning_line_item",
  "data": {
    "pay_stub": {
      "id": "<id>",
      "object": "pay_stub",
      "links": {
        "self": "/pay_stubs/<id>"
      }
    },
    "amount": 3000,
    "custom_amount": 3000,
    "managed_amount": null,
    "is_managed": false,
    "line_item_type": "earning",
    "earning_type": {
      "id": "<id>",
      "object": "earning_type",
      "data": {
        "type": "wage",
        "label": "Wage",
        "supported_payroll_types": {
          "regular": true,
          "historical": true,
          "off_cycle": true
        }
      },
      "links": {
        "self": "/earning_types/wage"
      }
    },
    "hours": 0,
    "managed_hours": null,
    "custom_hours": 0,
    "accrued_vacation_pay": 0,
    "recurrence": null,
    "pay_rate": null,
    "overtime_rate": null,
    "title": "Earning",
    "title_translations": null,
    "title_translated": "Earning",
    "expense_accounting_code": null,
    "managed_expense_accounting_code": null,
    "custom_expense_accounting_code": null,
    "liability_accounting_code": null,
    "managed_liability_accounting_code": null,
    "custom_liability_accounting_code": null,
    "business_preset": null,
    "source_adjustment": null,
    "component_settings": {
      "attributes_locked": false
    },
    "earned_on": null,
    "managed_earned_on": null,
    "custom_earned_on": null,
    "external_ref": null,
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/earning_line_items/<id>"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

pay_stub_id

string

required

business_preset_id

string

earning_type

enum<string>

The type of earning for this line item.

Must be present when business_preset_id is either empty or not set.

Available options:

bonus_discretionary,

bonus_non_discretionary,

bonus_non_taxable,

commission,

commission_periodic,

commission_self_employed,

death_benefit,

gift_cash,

gratuity,

in_lieu_wages,

income_replacement_indemnity_non_taxable,

income_replacement_indemnity_taxable,

invoice_payment,

invoice_sales_tax,

leave_bereavement,

leave_citizenship,

leave_domestic_and_sexual_violence,

leave_general,

leave_jury_duty,

leave_maternity,

leave_organ_donor,

leave_parental,

leave_paternity,

leave_personal,

leave_sick,

leave_voting,

leave_wedding,

overtime,

parental_top_up_insurable,

parental_top_up_non_insurable,

pension,

retiring_allowance,

retiring_allowance_eligible,

retroactive_pay,

retroactive_pay_increase,

salary,

salary_continuance,

severance_pay,

statutory_holiday_pay,

supplemental_unemployment,

time_off_in_lieu,

time_off_in_lieu_overtime,

vacation_accrual_adjustment,

vacation_pay,

vacation_pay_employee_terminated,

vacation_pay_no_time_taken,

vacation_pay_time_taken,

wage

pay_rate_id

string

On line items of type wage and overtime you may pass a pay_rate_id and hours to automatically calculate the amount.

overtime_rate_id

string

On line items of type overtime you may pass a overtime_rate_id and hours to automatically calculate the amount.

custom_amount

number<decimal>

An override for managed_amount. When set, amount reflects this value instead of managed_amount.

Required range: x <= 999999

custom_hours

number<decimal>

An override for managed_hours. When set, hours reflects this value instead of managed_hours. Can be used to prorate the dollar amount on salary line items.

Required range: x <= 9999

accrued_vacation_pay

number<decimal>

The vacation pay accrued on this line item, calculated based on the Work Assignment's Vacation Pay Settings.

Required range: -99999 <= x <= 99999

title

string | null

Maximum string length: 255

title_translations

object | null

Optional translations for the title property.

Hide child attributes

title_translations.en

string

Maximum string length: 255

title_translations.fr

string

Maximum string length: 255

component_settings

object

Hide child attributes

component_settings.attributes_locked

boolean

expense_accounting_code_id

string

custom_expense_accounting_code_id

string

liability_accounting_code_id

string

custom_liability_accounting_code_id

string

custom_earned_on

string<date>

external_ref

string

Maximum string length: 255

custom_tag_assignment

object

Hide child attributes

custom_tag_assignment.unit

enum<string>

Available options:

amount,

hours,

percentage

custom_tag_assignment.is_component_locked

boolean

custom_tag_assignment.tag_allocations

object[]

Hide child attributes

custom_tag_assignment.tag_allocations.tags

string[]

custom_tag_assignment.tag_allocations.value

number<decimal>

Required range: x >= 0

Response

201 - application/json

Created

string

read-only

The unique identifier of the object in Nmbr.

object

string

read-only

The type of the object in Nmbr ("earning_line_item").

data

Earning Line Item · object

Hide child attributes

data.pay_stub

object

Hide child attributes

data.pay_stub.id

string

read-only

The unique identifier of the object in Nmbr.

data.pay_stub.object

string

read-only

The type of the object in Nmbr ("pay_stub").

data.amount

number<decimal> | null

The effective amount for this line item. Returns custom_amount if set, otherwise managed_amount. Read-only.

data.custom_amount

number<decimal> | null

An override for managed_amount. When set, amount reflects this value instead of managed_amount.

data.managed_amount

number<decimal>

The amount calculated by the system or set by the linked Earning or Pay Rate. Read-only; set custom_amount to override.

data.is_managed

boolean

Whether this line item was generated by an Earning or Pay Rate recurrence and calculated automatically. When true, only custom_amount and custom_hours can be modified and the line item cannot be deleted.

data.line_item_type

string | null

data.earning_type

object

The type of earning for this line item.

Hide child attributes

data.earning_type.id

string

read-only

The unique identifier of the object in Nmbr.

data.earning_type.object

string

read-only

The type of the object in Nmbr ("earning_type").

data.earning_type.data

Earning Type · object

Hide child attributes

data.earning_type.data.type

string | null

The string identifier for this earning type.

data.earning_type.data.label

string | null

The human-readable display name for this earning type.

data.earning_type.data.supported_payroll_types

object | null

A map of Payroll types to whether this earning type is available on that Payroll type.

Hide child attributes

data.earning_type.data.supported_payroll_types.regular

boolean

data.earning_type.data.supported_payroll_types.historical

boolean

data.earning_type.data.supported_payroll_types.off_cycle

boolean

data.earning_type.data.features

object[]

Hide child attributes

data.earning_type.data.features.type

enum<string>

The payroll calculation this entry describes.

Available options:

eht,

income_tax,

insurable,

pensionable,

vacationable,

wcb

data.earning_type.data.features.label

string

Human-readable name for the payroll calculation.

data.earning_type.data.features.definitions

object[]

How this type affects the calculation, broken down by jurisdiction. Jurisdictions where it does not apply are omitted.

Hide child attributes

data.earning_type.data.features.definitions.jurisdiction

string

The jurisdiction this applies to (e.g. ca_federal, ca_on, ca_qc).

data.earning_type.data.features.definitions.effects

enum<string>[]

How this type affects the payroll calculation in this jurisdiction.

Available options:

accrues_vacation_pay,

reduces_base,

tax_credit,

withholding

data.earning_type.data.features.definitions.help_text

string | null

Plain-language explanation of how this type affects the calculation in this jurisdiction.

data.earning_type.data.features.definitions.program_label

string | null

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

data.earning_type.data.form_mappings

object[]

Hide child attributes

data.earning_type.data.form_mappings.form

string

The form code (e.g. t4).

data.earning_type.data.form_mappings.form_label

string

Human-readable form name.

data.earning_type.data.form_mappings.mapping

object[][]

The boxes on the form this type contributes to.

Hide child attributes

data.earning_type.data.form_mappings.mapping.name

string

The box or line identifier on the form.

data.earning_type.data.form_mappings.mapping.help_text

string | null

Plain-language explanation of the box, when available.

data.hours

number<decimal> | null

The effective hours for this line item. Returns custom_hours if set, otherwise managed_hours. null if neither is set. Read-only.

data.managed_hours

number<decimal> | null

The default hours from the linked Pay Rate. Read-only; set custom_hours to override.

data.custom_hours

number<decimal> | null

An override for managed_hours. When set, hours reflects this value instead of managed_hours. Can be used to prorate the dollar amount on salary line items.

data.accrued_vacation_pay

number<decimal> | null

The vacation pay accrued on this line item, calculated based on the Work Assignment's Vacation Pay Settings.

data.recurrence

any

data.pay_rate

any

data.overtime_rate

any

data.title

string | null

Maximum string length: 255

data.title_translations

object | null

Optional translations for the title property.

Hide child attributes

data.title_translations.en

string

Maximum string length: 255

data.title_translations.fr

string

Maximum string length: 255

data.title_translated

string

read-only

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

data.expense_accounting_code

any

The effective expense accounting code. Returns the user-set value if present, otherwise the system-derived value. Writes to this field set the user override.

data.managed_expense_accounting_code

any

The expense accounting code derived by the system from accounting code rules and presets. Read-only.

data.custom_expense_accounting_code

any

User-set expense accounting code that overrides the system-derived value.

data.liability_accounting_code

any

The effective liability accounting code. Returns the user-set value if present, otherwise the system-derived value. Writes to this field set the user override.

data.managed_liability_accounting_code

any

The liability accounting code derived by the system from accounting code rules and presets. Read-only.

data.custom_liability_accounting_code

any

User-set liability accounting code that overrides the system-derived value.

data.business_preset

any

data.source_adjustment

any

data.component_settings

object | null

Settings specific to the Nmbr component.

Hide child attributes

data.component_settings.attributes_locked

boolean

Whether the line item is locked and cannot be edited in the component.

data.earned_on

any

The effective earned-on date for this line item. Returns custom_earned_on if set, otherwise managed_earned_on. Read-only.

data.managed_earned_on

string<date> | null

The earned-on date set by the system. Read-only; set custom_earned_on to override.

data.custom_earned_on

string<date> | null

An override for managed_earned_on. When set, earned_on reflects this value instead of managed_earned_on. Must fall within the payroll's pay period.

data.external_ref

string | null

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.

Maximum string length: 255

data.created_at

string<dateTime>

read-only

The date and time the object was created in Nmbr.

data.updated_at

string<dateTime>

read-only

The date and time the object was last updated in Nmbr.

List earning line items Retrieve an earning line item

⌘I

Overview

Bulk & Batch Operations

Partner

Companies

Employees

Contractors

Payrolls

Line Items

Banking

Reporting

Forms

Vacation Pay

Lookups

Calculations

Miscellaneous

Create an earning line item

Authorizations

Body

Response