A payroll represents a single payroll run for a company — covering a specific pay period, with a status that progresses from draft through processing to paid. The payroll object includes financial totals and, in its detail form, per-employee line items and contractor payments.
Payroll endpoints require a payroll or premium plan.
Shape Returned by Extra fields List item GET /payrolls— Detail GET /payrolls/:payroll_iditems, contractor_payments
The detail shape is a superset of the list shape.
Field Type Description idstring Unique payroll identifier (e.g. "pay_abc123def456"). period_startstring Pay period start date (YYYY-MM-DD). period_endstring Pay period end date (YYYY-MM-DD). paydaystring Date employees are paid (YYYY-MM-DD). statusstring Current payroll status. See Statuses below. typestring Payroll type: "regular" or "off_cycle". pay_frequencystring Pay frequency: "weekly", "biweekly", "semimonthly", or "monthly".
Field Type Description approval_deadlinedate-time Deadline to approve before auto-processing. approved_atdate-time | null When the payroll was approved. Null if not yet approved. processing_periodstring Number of business days for processing (e.g. "four_day"). managedboolean Whether this payroll is managed by the platform. autopayboolean Whether this payroll is on autopay. off_cycle_optionsobject | null Options for off-cycle payrolls. Null for regular payrolls.
Field Type Description pay_schedule_group_idinteger | null ID of the pay schedule group this payroll belongs to. pay_schedule_groupobject | null Pay schedule group summary with pay_schedule_group_id, name, and is_default. See Pay Schedule Group .
Field Type Description totalsPayroll Totals | nullAggregate financial totals for the payroll.
Field Type Description itemsarray (Detail only) Per-employee payroll items. See Payroll Item .contractor_paymentsarray (Detail only) Per-contractor payments. See Contractor Payment .
Value Description "draft"Payroll created but not yet approved. Can be edited or deleted. "pending"Approved and awaiting processing. "processing"Currently being processed by the payroll provider. "paid"Successfully processed and paid. "failed"Processing failed. "partially_paid"Some payments succeeded, others failed. "skipped"Payroll was skipped (no employees or manually skipped).
Field Type Description payrollstring Payroll ID this totals record belongs to. employee_grossstring Total employee gross pay. employee_reimbursementsstring Total employee reimbursements. employee_taxesstring Total employee tax withholdings. employee_benefitsstring Total employee benefit deductions. post_tax_deductionsstring Total post-tax deductions. employee_netstring Total employee net pay. contractor_grossstring Total contractor gross pay. contractor_reimbursementsstring Total contractor reimbursements. contractor_netstring Total contractor net pay. company_taxesstring Employer-side tax liability. company_benefitsstring Employer-side benefit costs. liabilitystring Total liability for this payroll. cash_requirementstring Total cash required to fund this payroll.
Field Type Description idstring Unique payroll item identifier. employeestring External employee identifier. statusstring Item payment status. payment_methodstring "direct_deposit" or "manual".net_paystring | null Net pay for this employee. earningsarray Earnings breakdown entries. reimbursementsarray Reimbursement entries. taxesarray Tax withholding entries. benefitsarray Benefit deduction entries. post_tax_deductionsarray Post-tax deduction entries (e.g. garnishments, Roth 401k).
Field Type Description idstring Unique contractor payment identifier. contractorstring External contractor identifier. statusstring Payment status. payment_methodstring "direct_deposit" or "manual".amountstring Payment amount. reimbursement_amountstring Reimbursement amount. net_paystring Contractor net pay.
JSON
{
"id": "pay_abc123def456",
"period_start": "2026-02-17",
"period_end": "2026-03-02",
"approval_deadline": "2026-03-04T17:00:00.000Z",
"approved_at": "2026-03-04T14:30:00.000Z",
"payday": "2026-03-07",
"status": "paid",
"type": "regular",
"pay_frequency": "biweekly",
"processing_period": "four_day",
"managed": true,
"autopay": false,
"off_cycle_options": null,
"pay_schedule_group_id": 3,
"totals": {
"payroll": "pay_abc123def456",
"employee_gross": "12500.00",
"employee_reimbursements": "150.00",
"employee_taxes": "2875.00",
"employee_benefits": "600.00",
"post_tax_deductions": "200.00",
"employee_net": "8975.00",
"contractor_gross": "3000.00",
"contractor_reimbursements": "0.00",
"contractor_net": "3000.00",
"company_taxes": "1562.50",
"company_benefits": "450.00",
"liability": "14137.50",
"cash_requirement": "14137.50"
},
"pay_schedule_group": {
"pay_schedule_group_id": 3,
"name": "Biweekly Salaried",
"is_default": true
}
} 