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
string
Unique identifier for the payroll, e.g.
pr_244UfG.string
ID of the legal entity that owns and funds the payroll.
string | null
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.string
The status of the payroll. Possible values are
draft, pending, blocked, overdue,
processing, failed, paid or void.string | null
A free-text note attached to the payroll.
string | null
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.
string | null
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.string | null
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.object
The pay period the payroll covers.
array
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.
string
Unique identifier for the payroll item, e.g.
pri_YogJe.string
ID of the payroll the item belongs to.
string
ID of the legal entity that funds the item. Matches the payroll’s
entity.string | object
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.string
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.string | null
regular or off_cycle, as on the payroll.string
Two-letter ISO country code of the country the worker is paid in, in uppercase.
string
Three-letter ISO currency code of the item, in uppercase. Every line’s
destination_currency
matches it.string
The date the worker is paid.
string | null
The last moment changes to the item are accepted before it is processed, as an ISO 8601
timestamp with offset.
object
The pay period the item covers.
array
Gross pay lines, such as regular pay, overtime, bonuses and taxable non-cash earnings. Each is
an amount.
array
Tax lines. Each is an amount whose
payer says whether the company pays it or it is
withheld from the worker.array
Company contributions to the worker’s benefits. Each is an amount. The worker’s own
contributions appear under
deductions.array
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.
object
Gross pay: the sum of the
earnings lines.object
Taxes split by who pays them.
object
Company benefit contributions: the sum of the
benefits lines.object
The sum of the
reimbursements lines.object
The sum of the
deductions lines.object
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.
string | null
The label of the line, e.g.
Regular or Federal Income Tax. null on totals.string | null
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.string | null
The amount as it was recorded.
null only in a blank net total, described above.string | null
Three-letter ISO currency code of
source_amount, in uppercase. null only in a blank net total.string | null
The amount in the item’s currency. Equal to
source_amount when no conversion was needed.
null only in a blank net total.string | null
Three-letter ISO currency code of
destination_amount, in uppercase. Matches the item’s
currency. null only in a blank net total.string | null
The hours behind an earnings line, for hourly pay.
null on other lines.string | null
The payroll provider’s identifier for the line, when it has one.
string | null
On tax lines,
company when the company pays the tax or worker when it is withheld from the
worker. null on other lines.string | null
On benefit and deduction lines,
pre_tax or post_tax says how the line is treated for tax.
null on other lines.