--- updatedAt: 2026-10-07T20:42:51.000Z agentTools: projectIndex: https://docs.checkhq.com/llms.txt --- # The payroll object Contains the total amount of money to withdraw from the company's account as part of paying employees and each employee’s compensation components. The Payroll object captures the wages earned by employees in a given pay period for a specific payday. You can preview the payroll to generate net pay, after taxes, benefit deductions, and post tax deductions, and then approve the payroll to confirm the calculations, and transition the payroll into the `pending` status. For more details, check out the [Life of a Payroll](https://docs.checkhq.com/docs/life-of-a-payroll) guide. By default, [Payroll Items](https://docs.checkhq.com/reference/the-payroll-item-object) and [Contractor Payments](https://docs.checkhq.com/reference/the-contractor-payment-object) are not shown on their associated Payroll. However, Payrolls with 500 or fewer payroll items and contractor payments may optionally use the query parameters `include_items` and `include_contractor_payments` to create, view, and update Payroll Items and Contractor Payments directly in-line with the Payroll. > **Shared enums:** The `status` field on this object uses the same set of values as the `status` field on the [Payroll Item](https://docs.checkhq.com/reference/the-payroll-item-object) object: `draft`, `pending`, `processing`, `failed`, `partially_paid`, or `paid`. The `pay_frequency` field uses the same set of values as `pay_frequency` on the [Company](https://docs.checkhq.com/reference/company) object and the [Pay Schedule](https://docs.checkhq.com/reference/the-pay-schedule-object) object. ```json Sample approved payroll object { "id": "pay_Z26PNMC7Ky1wfFQzVqfF", "company": "com_sx3svU6K8c5ZkSFlOh5p", "period_start": "2019-06-16", "period_end": "2019-06-29", "reopen_deadline": "2019-07-02T00:00:00.000000Z", "approval_deadline": "2019-07-02T00:00:00.000000Z", "approved_at": "2019-06-29T18:26:56.848920Z", "payday": "2019-07-05", "status": "paid", "type": "regular", "pay_frequency": "biweekly", "funding_payment_method": "ach", "processing_period": "three_day", "off_cycle_options": null, "managed": true, "fulfillment": null, "correction": null, "preview": { "status": "succeeded", "started_at": "2019-06-29T18:26:56.848920Z" }, "totals": { "employee_gross": "961.54", "employee_reimbursements": "0.00", "employee_taxes": "249.23", "employee_benefits": "0.00", "post_tax_deductions": "0.00", "employee_net": "712.31", "contractor_gross": "100.00", "contractor_reimbursements": "15.00", "contractor_net": "115.00", "company_taxes": "73.56", "company_benefits": "0.00", "liability": "1150.10", "cash_requirement": "1150.10" }, "is_void": false, "warnings": [], "metadata": {} } ``` ```json Sample payroll object with include_items { "id": "pay_Z26PNMC7Ky1wfFQzVqfF", "company": "com_sx3svU6K8c5ZkSFlOh5p", "period_start": "2019-06-16", "period_end": "2019-06-29", "approval_deadline": "2019-07-02T00:00:00.000000Z", "approved_at": "2019-06-29T18:26:56.848920Z", "payday": "2019-07-05", "status": "paid", "type": "regular", "pay_frequency": "biweekly", "funding_payment_method": "ach", "processing_period": "three_day", "off_cycle_options": null, "managed": true, "fulfillment": null, "correction": null, "preview": { "status": "succeeded", "started_at": "2019-06-29T18:26:56.848920Z" }, "totals": { "employee_gross": "961.54", "employee_reimbursements": "0.00", "employee_taxes": "249.23", "employee_benefits": "0.00", "post_tax_deductions": "0.00", "employee_net": "712.31", "contractor_gross": "100.00", "contractor_reimbursements": "15.00", "contractor_net": "115.00", "company_taxes": "73.56", "company_benefits": "0.00", "liability": "1150.10", "cash_requirement": "1150.10" }, "items": [ { "id": "itm_yvmmsVGFxLoBaMIkqzea", "payroll": "pay_Z26PNMC7Ky1wfFQzVqfF", "employee": "emp_zGGp6wYcxAeu1Ng8IA7v", "status": "draft", "payment_method": "direct_deposit", "net_pay": "712.31", "earnings": [ { "amount": "961.54", "hours": 40.0, "type": "hourly", "workplace": "wrk_cxcG4vjGKcSXZk1fgKai", "code": null, "description": null } ], "reimbursements": [], "taxes": [ { "tax": "tax_I1Z9zqbBGWIbvlZpN2Vq", "description": "New York SDI", "amount": "0.60", "payer": "employee" }, { "tax": "tax_ImvSF9CTuMdokf0uwx5x", "description": "Employer FICA Tax", "amount": "59.62", "payer": "company" }, { "tax": "tax_yjNkKk061BTipYv7G4Ti", "description": "New York City Tax", "amount": "31.04", "payer": "employee" }, { "tax": "tax_S1krAkh75RzdWu5J53HA", "description": "New York State Tax", "amount": "44.20", "payer": "employee" }, { "tax": "tax_UJrIQbtVErbdez0bYTVN", "description": "New York Family Leave Benefits", "amount": "1.47", "payer": "employee" }, { "tax": "tax_1XHqR9Qf5t18SD2sfYEe", "description": "Medicare", "amount": "13.94", "payer": "employee" }, { "tax": "tax_8L3JLfsH4X6dp0maBWfW", "description": "Federal Income Tax", "amount": "98.36", "payer": "employee" }, { "tax": "tax_ibU8cGhC5OlpOjoQFIXV", "description": "FICA", "amount": "59.62", "payer": "employee" }, { "tax": "tax_O3f21hkS1cvHBZTa61BO", "description": "Employer Medicare Tax", "amount": "13.94", "payer": "company" } ], "benefits": [], "benefit_overrides": [], "post_tax_deductions": [], "post_tax_deduction_overrides": [], "warnings": [] } ], "is_void": false, "warnings": [], "metadata": {} } ```
Attribute Description
`id` _string_ Unique identifier for the payroll.
`company` _string_ ID of the [company](https://docs.checkhq.com/reference/company) that the payroll relates to.
`period_start` _YYYY-MM-DD_ Start of the date range that the payroll covers.
`period_end` _YYYY-MM-DD_ End of the date range that the payroll covers.
`reopen_deadline` _datetime_ Datetime by which the payroll can be reopened, when in `pending` status. See [Payroll Status](https://docs.checkhq.com/docs/life-of-a-payroll#pending).
`approval_deadline` _datetime_ Datetime by which the payroll must be approved.
`approved_at` _datetime_ Datetime at which the payroll was approved. `null` for payrolls with a **status** of `draft`.
`payday` _YYYY-MM-DD_ Date on which [employees](https://docs.checkhq.com/reference/the-employee-object) will be paid for the payroll. A list of valid paydays for payrolls paid via direct deposit is available in the `/paydays` endpoint.
`status` _string_ Status of the payroll in its [lifecycle](https://docs.checkhq.com/docs/life-of-a-payroll). One of `draft`, `pending`, `processing`, `failed`, `partially_paid`, or `paid`.
`type` _string_ Indicates whether the payroll is a regular, [off-cycle](https://docs.checkhq.com/docs/off-cycle-payroll), or amendment payroll. One of `regular`,`off_cycle`, `amendment`, `balancing` or `third_party_sick_pay`.
`pay_frequency` _string_ Frequency by which [employees](https://docs.checkhq.com/reference/the-employee-object) get paid. One of `weekly`, `biweekly`, `semimonthly`, `monthly`, `quarterly`, or `annually`.
`funding_payment_method` _string_ Payment method for funding the payroll. One of `ach`, `wire`, or `parafin`. Partners can set `ach` or `wire` when creating or updating a payroll. Check sets `parafin` when a payroll advance is accepted for an approved payroll; this value cannot be set or changed via the API.
`pay_schedule` _string_ ID of the [pay schedule](https://docs.checkhq.com/reference/the-pay-schedule-object) that the payroll relates to.
`processing_period` _string_ The processing period for this payroll. If not explicitly set, this value is set to the company's processing period at the time when the payroll is created. For `two_day`-approved companies, the processing period for the _particular payroll_ can be upgraded to `one_day` without restriction. On the other hand, the request would fail for `three_day`-approved companies. _Note:_ For `three_day` payrolls, funding by ACH is limited to a $1M cash requirement. Payrolls over $1M require funding by wire or can be broken up into multiple payrolls with cash requirements less than $1M.
`off_cycle_options` _[off-cycle options](https://docs.checkhq.com/reference/payroll-off-cycle-options) object_ Additional configuration options controlling [off-cycle](https://docs.checkhq.com/docs/off-cycle-payroll) payroll behavior. `null` for payrolls of **type** `regular`.
`managed` _boolean_ Indicates whether the payroll's [lifecycle](https://docs.checkhq.com/docs/life-of-a-payroll) is being managed by Check.
`fulfillment` _string or null_ ID of the [fulfillment](https://docs.checkhq.com/reference/the-fulfillment-object) created when a balancing payroll is fulfilled. `null` for non-balancing payrolls and for balancing payrolls that have not yet been fulfilled.
`preview` _[preview](https://docs.checkhq.com/reference/the-preview-object) object_ The status and datetime of the most recent preview calculation for the payroll. `null` if the payroll has not yet been previewed, or if the payroll or any related payroll items or contractor payments were modified after the most recent preview.
`totals` _[totals](https://docs.checkhq.com/reference/payroll-totals) object_ Calculated totals for various payroll categories. `null` for payrolls with a **status** of `draft` outside of the [preview](https://docs.checkhq.com/reference/preview-payroll) endpoint.
`items` _array of[payroll item](https://docs.checkhq.com/reference/the-payroll-item-object) objects_ The set of [payroll items](https://docs.checkhq.com/reference/the-payroll-item-object) associated with the payroll. Only returned if `include_items` is set to true. Note only one payroll item per employee is allowed per payroll.
`contractor_payments` _array of[contractor payment](https://docs.checkhq.com/reference/the-contractor-payment-object) objects_ The set of [contractor payments](https://docs.checkhq.com/reference/the-contractor-payment-object) associated with the payroll. Only returned if `include_contractor_payments` is set to true. Note only one contractor payment per contractor is allowed per payroll.
`correction` _string or null_ ID of the [correction](https://docs.checkhq.com/reference/the-correction-object) this payroll is an operation of. `null` if the payroll is not attached to a correction. On create, pass `correction` to attach a managed replacement payroll to a draft correction. On update, `correction` may be included only to restate the payroll's current correction ID; a different value is rejected.
`is_void` _boolean_ Indicates whether a payroll is a [void](https://docs.checkhq.com/docs/voiding-a-payroll-item).
`warnings` List of payroll [warnings](https://docs.checkhq.com/reference/payroll-warnings#the-payroll-warning-object) objects.
`fulfillment` ID of the related [Fulfillment](https://docs.checkhq.com/reference/fulfillments), if applicable. _A common use-case would be displaying a Tax Receipt from the related Fulfillment object in a period-end balancing payroll. _
`metadata` _object_ Additional loosely structured information to associate with the payroll.
`bank_account` _string_ ID of the [bank account](https://docs.checkhq.com/reference/bank-accounts-1) that will be used to fund the payroll.
`simulation_mode` _string_ Sandbox-only. Indicates whether a payroll will automatically transition from `pending` to `processing` to `paid`. One of `automatic` or `manual`.