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 guide.

By default, Payroll Items and Contractor Payments 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 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 object and the Pay Schedule 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,
  "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": {}
}

{
  "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,
  "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 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.
`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 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. One of `draft`, `pending`, `processing`, `failed`, `partially_paid`, or `paid`.
`type` string	Indicates whether the payroll is a regular, off-cycle, or amendment payroll. One of `regular`,`off_cycle`, `amendment`, `balancing` or `third_party_sick_pay`.
`pay_frequency` string	Frequency by which employees get paid. One of `weekly`, `biweekly`, `semimonthly`, `monthly`, `quarterly`, or `annually`.
`funding_payment_method` string	Payment method for funding the payroll. One of `ach` or `wire`.
`pay_schedule` string	ID of the pay schedule 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 object	Additional configuration options controlling off-cycle payroll behavior. `null` for payrolls of type `regular`.
`managed` boolean	Indicates whether the payroll's lifecycle is being managed by Check.
`fulfillment` string or null	ID of the fulfillment created when a balancing payroll is fulfilled. `null` for non-balancing payrolls and for balancing payrolls that have not yet been fulfilled.
`preview` preview 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 object	Calculated totals for various payroll categories. `null` for payrolls with a status of `draft` outside of the preview endpoint.
`items` array ofpayroll item objects	The set of payroll items 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 ofcontractor payment objects	The set of contractor payments 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.
`is_void` boolean	Indicates whether a payroll is a void.
`warnings`	List of payroll warnings objects.
`fulfillment`	ID of the related Fulfillment, 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 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`.