pay_date, will automatically have all recurring earnings, allowances, reimbursements, deductions and benefits populated on its Pay Stubs.
Interacting with payrolls
You can retrieve a list of payrolls from the payroll API endpoint: Requestemployee_summary.subtractions is the total of everything withheld from the employee’s gross to reach net pay: statutory withholdings (income tax, CPP, EI), deductions (e.g. union dues), and the employee’s benefit contributions.
Each Pay Stub carries a per-employee employee_summary, a company_summary, and a line_item_summary that breaks the totals down by category: earnings, statutory withholdings, deductions, employee and employer benefits, reimbursements, and allowances.
Query the pay stub endpoint for the Pay Stubs on a specific payroll id:
Request
Filtering the payrolls list
GET /payrolls requires either a business_entity_id or a pay_schedule_id. Without one of them, the request returns a 422.
The status filter accepts one or more comma-separated values. Pass several to retrieve everything in flight in a single call:
Request
422.
To retrieve every payroll except certain statuses, use not_status with the same comma-separated form:
Request
not_status are ignored rather than rejected, so check them against the documented statuses.
Retrieving the upcoming regular draft payroll
To retrieve the upcoming regular draft payroll (the next payroll that is ready for editing), filter the payrolls index bytype=regular and status=draft, and sort by pay_date:
Request
type=regular filter returns regular payrolls only. Off-cycle and historical payrolls are excluded, so query them separately if you need them.
📘 Why not useYou can update an individual payroll line item using the API. The example below could be used to enter 10 hours for the given pay rate.next_payrolls? Thenext_payrolls=onlyfilter returns the current payroll being handled by Nmbr for each Pay Schedule, which may be anapproved,processing, orfailedpayroll, not necessarily one that is ready for editing. Filtering bytype=regular&status=draftand sorting bypay_dateensures you always get the next editable regular payroll.
Approving payroll
When a payroll is approved (via the/payrolls/<payroll_id>/approve endpoint), its status changes to approved. Once approved, the payroll can no longer be modified. This is because the taxes, net pay, and benefits have been calculated and saved for the payroll.
📘 Rejected Approvals If a payroll is in an invalid state when theOnce a payroll is approved, Nmbr collects the funds from the employer’s bank account, sends net pay to employees’ bank accounts on payday, and remits tax payments on time. Follow a payroll through each phase using its/approveendpoint is called, the approval will fail, returning a422 Unprocessable Entityresponse. Common reasons for failure include:
- The payroll is past its approval deadline.
- A pay stub has a negative net amount.
- The payroll has stale calculations and needs to be recalculated.
- The payroll is not in the
draftstatus.
status field.
A payroll has one of five statuses: draft, approved, processing, paid, and failed. The rest of this section covers what each status means and how a payroll moves between them.
📘 Payroll webhooks Nmbr can notify your app as a payroll moves through its lifecycle. Subscribe to thepayroll_approved,payroll_unapproved,payroll_paid, andpayroll_deadline_upcomingevents instead of polling. See Webhooks for the setup and payload shape.
Payroll Status Lifecycle
draft
When a payroll is first created, it will be in the draft status. You can modify a draft payroll in any way you see fit. Payments to employees can be added and removed, earnings and hours worked can be modified on individual payroll items, etc. You can only delete a payroll while it’s in draft.approved
When a payroll is approved (via the/payrolls/<payroll_id>/approve endpoint), its status changes to approved. Once approved, the payroll can no longer be modified. This is because the taxes, net pay, and benefits have been calculated and saved for the payroll.
If you determine that an error exists in the payroll, you can move it back to the draft status (via the /payrolls/<payroll_id>/unapprove endpoint). Once back in draft, the payroll can again be modified, previewed, and even deleted. If and when it is approved again, the payroll moves back into the approved status.
processing
Each business day, once the 4:30 PM ET approval deadline passes, Nmbr collects the approved payrolls due that day and begins moving the money to pay them out using Electronic Funds Transfer (EFT). The first step debits the payroll’scash_requirement from the employer’s bank account. Once that debit is submitted, the payroll moves into processing.
A processing payroll can no longer be moved back to draft. If you need to change a payroll that is already processing, contact Nmbr.
paid
Before employees are paid, the employer debit has to settle. Once Nmbr has the employer’scash_requirement, it sends net pay to each employee set up for direct deposit. When those payments are sent, the payroll reaches its final status: paid.
The number of business days between approval and payday depends on the business entity’s configured processing speed. Read the current value from effective_processing_speed on the business entity.
partially_paid
Deprecated. No payroll reaches this status today, and you should not filter on it. It remains a valid value only for backwards compatibility. When a payment to an employee or contractor is returned (most often from an invalid account or transit/institution number, or a frozen bank account), Nmbr marks that individual payment as failed and leaves the parent payroll inprocessing. There is no payroll-level “partially paid” signal. To find failures, check the child payment records for a failed status, then contact Nmbr to resolve one.
failed
The employer debit can also be returned, most often because the employer’s bank account had insufficient funds at the time of the request. When this happens, Nmbr sets the payroll’s status tofailed and, where possible, pauses any in-flight employee and contractor payments for that payroll. Nmbr then works with you to wire the cash_requirement for the failed payroll, then releases the paused payments and delivers them.