Payroll object is used to represent a group of individual payroll items related to
a specific pay schedule, legal entity, and processing date. The entity field identifies
the entity that owns and funds the payroll.
Plane uses Payrolls to represent all recurring payments to your team members, whether they’re employees or contractors,
as part of our Unified Payroll architecture.
When a Payroll is processed, it will usually result in a series of Payments
to the individuals that were included in that payroll.
For team members who are not paid regularly, or for vendors,
you will create Payment objects directly.
A payroll is made of payroll items, each one worker’s slice of the run. Usually a worker has one
item on a payroll, but a skipped item and its replacement can sit on the same payroll, so do not key
items by worker. Each item carries the worker’s earnings, taxes,
benefits, reimbursements and deductions as individual lines, and every line and every total
is the same amount shape. List payrolls returns the
payroll with its totals. Get a payroll adds the items.
Attributes
regular for a payroll generated by a pay schedule, or off_cycle for one run outside the
schedule, such as a bonus or correction run.The status of the payroll. Possible values are
draft, pending, blocked, overdue,
processing, failed, paid or void.
blocked persists until explicitly handled; passing a deadline does not make it
overdue. overdue applies only before processing begins.The date by which funding must reach Plane for the payroll to pay out on time. Returned by
List payrolls and not included on Get a payroll.
ID of the pay schedule that generated the payroll.
null for off-cycle payrolls. Returned by
List payrolls and not included on Get a payroll.How often the pay schedule runs. Possible values are
weekly, biweekly, twice_monthly or
monthly. Returned by List payrolls and not included on
Get a payroll.The payroll’s totals across all of its items, in the totals shape below.
The payroll items on the payroll, each one worker’s slice. Only returned by
Get a payroll.
Payroll item
One worker’s slice of a payroll. Items carry the sametotals shape as the payroll, plus the
individual lines those totals are summed from.
ID of the worker being paid. Pass
expand[]=worker on Get a payroll
to receive an object with the worker’s id, name and type instead.The status of the item. Possible values are
draft, pending, blocked, overdue, skipped,
processing, failed, paid or void. A skipped item was excluded from the payroll run.
A blocked item stays blocked after its deadline until explicitly handled.
An item that has entered processing cannot become overdue, even during retries.Three-letter ISO currency code of the item, in uppercase. Every line’s
destination_currency
matches it.The last moment changes to the item are accepted before it is processed, as an ISO 8601
timestamp with offset.
The item’s totals, in the totals shape below.
Gross pay lines, such as regular pay, overtime, bonuses and taxable non-cash earnings. Each is
an amount.
Tax lines. Each is an amount whose
payer says whether the company pays it or it is
withheld from the worker.Company contributions to the worker’s benefits. Each is an amount. The worker’s own
contributions appear under
deductions.Expense reimbursements paid alongside earnings. Each is an amount.
Amounts withheld from the worker, including the worker’s benefit contributions and post-tax
deductions such as loan repayments. Each is an amount.
Totals
Sums of the lines on a payroll item, or across every item on a payroll. Each field is an amount with only its amount and currency fields set; the descriptive fields arenull.
On earnings, benefits, reimbursements and deductions, hours is the sum of the lines’
hours, "0.0" when none of them carry hours. On taxes and net it is null.
What the worker receives: gross pay less worker taxes, deductions and any non-cash earnings,
plus reimbursements. For payrolls run through an employer of record, where Plane does not see
worker taxes, every field of
net may be null.Amount
A single line on a payroll item, or a total. Amounts are decimal strings. The amount and currency fields are always set, except in a blanknet total, where every field of the amount is null
(see Totals). The remaining fields are null wherever they do not apply, as noted on
each one below.
A code for the kind of line, e.g.
regular, bonus or other_imputed for earnings, and
section_125_medical, hsa or retirement for benefits and deductions. null where no code
applies, including on totals.Three-letter ISO currency code of
source_amount, in uppercase. null only in a blank net total.The amount in the item’s currency. Equal to
source_amount when no conversion was needed.
null only in a blank net total.Three-letter ISO currency code of
destination_amount, in uppercase. Matches the item’s
currency. null only in a blank net total.On tax lines,
company when the company pays the tax or worker when it is withheld from the
worker. null on other lines.On benefit and deduction lines,
pre_tax or post_tax says how the line is treated for tax.
null on other lines.