---
title: "Cancel a payroll"
method: PUT
path: "/v1/companies/{company_id}/payrolls/{payroll_id}/cancel"
tags: ["Payrolls"]
---

# Cancel a payroll

`PUT /v1/companies/{company_id}/payrolls/{payroll_id}/cancel`

## Request

- Base URL: `https://api.gusto-demo.com`
- URL: `https://api.gusto-demo.com/v1/companies/{company_id}/payrolls/{payroll_id}/cancel`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gusto/apis/gusto-api/docs/v1/companies/:company_id/payrolls/:payroll_id/cancel/put.ts> (a function with typed inputs; its response is checked against the schema)

Transitions a `processed` payroll back to the `unprocessed` state. A payroll can be canceled if it meets both criteria:

- `processed` is `true`
- Current time is earlier than 4pm PT on the `payroll_deadline`

scope: `payrolls:run`

## Path parameters

- `company_id` string, required
- `payroll_id` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Response `200`

Successful

- UnprocessedPayroll: A payroll that has been transitioned back to unprocessed state after cancellation.
  - `payroll_deadline` string, date-time: A timestamp that is the deadline for the payroll to be run in order for employees to be paid on time. If payroll has not been run by the deadline, a prepare request will update both the check date and deadline to reflect the soonest employees can be paid and the deadline by which the payroll must be run in order for said check date to be met.
  - `check_date` string: The date on which employees will be paid for the payroll.
  - `processed` boolean: Whether or not the payroll has been successfully processed. Note that processed payrolls cannot be updated. Additionally, a payroll is not guaranteed to be processed just because the payroll deadline has passed. Late payrolls are not uncommon. Conversely, users may choose to run payroll before the payroll deadline.
  - `processed_date` string, nullable: The date at which the payroll was processed. Null if the payroll isn't processed yet.
  - `calculated_at` string, date-time, nullable: A timestamp of the last valid payroll calculation. Null if there isn't a valid calculation.
  - `uuid` string: The UUID of the payroll.
  - `payroll_uuid` string: The UUID of the payroll.
  - `company_uuid` string: The UUID of the company for the payroll.
  - `off_cycle` boolean: Indicates whether the payroll is an off-cycle payroll
  - `off_cycle_reason` 'Adhoc' | 'Benefit reversal' | 'Bonus' | 'Correction' | 'Dismissed employee' | 'Hired employee' | 'Wage correction' | 'Tax reconciliation' | 'Reversal' | 'Disability insurance distribution' | 'Transition from old pay schedule', nullable: The off-cycle reason. Only included for off-cycle payrolls.
  - `auto_payroll` boolean: Indicates whether the payroll has automatic payroll enabled
  - `external` boolean: Indicates whether the payroll is an external payroll
  - `pay_period` PayrollPayPeriodType
    - `start_date` string, nullable: The start date, inclusive, of the pay period.
    - `end_date` string, nullable: The start date, inclusive, of the pay period.
    - `pay_schedule_uuid` string, nullable: The UUID of the pay schedule for the payroll.
  - `created_at` string, date-time: Datetime for when the resource was created.
  - `partner_owned_disbursement` boolean, nullable: Will money movement for the payroll be performed by the partner rather than by Gusto?

## Other responses

- `404`: Not Found
- `422`: Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

## Changes

- **2026-11-03** `f98575fa2a5e`: 2 breaking
  - the response property `pay_period/end_date` became nullable for the status `200`
  - the response property `pay_period/start_date` became nullable for the status `200`

[Operation history](https://skmtc.dev/gusto/apis/gusto-api/changes/v1/companies/:company_id/payrolls/:payroll_id/cancel/put.md)

---

[API](https://skmtc.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)