Create an off-cycle payroll

post

https://api.gusto-demo.com/v1/companies/{company_id}/payrolls

Creates a new, unprocessed, off-cycle payroll.

`off_cycle_reason`

By default:

External benefits and deductions will be included when the off_cycle_reason is set to Correction.
All benefits and deductions are blocked when the off_cycle_reason is set to Bonus.

These elections can be overridden with the skip_regular_deductions boolean.

scope: payrolls:run

Path Params

company_id

string

required

The UUID of the company

Body Params

off_cycle

boolean

required

Whether it is an off cycle payroll.

off_cycle_reason

string

enum

required

An off cycle payroll reason. Select one from the following list.

Allowed:

start_date

date

required

Pay period start date.

end_date

date

required

Pay period end date.

pay_schedule_uuid

string

A pay schedule is required for transition from old pay schedule payroll to identify the matching transition pay period.

employee_uuids

array of strings | null

A list of employee uuids to include on the payroll.

employee_uuids

check_date

date

Payment date.

withholding_pay_period

string

enum

The payment schedule tax rate the payroll is based on.

Allowed:

skip_regular_deductions

boolean

Block regular deductions and contributions for this payroll.

fixed_withholding_rate

boolean

Enable taxes to be withheld at the IRS's required rate of 22% for federal income taxes. State income taxes will be taxed at the state's supplemental tax rate. Otherwise, we'll sum the entirety of the employee's wages and withhold taxes on the entire amount at the rate for regular wages.

is_check_only_payroll

boolean

When true, all employees in the payroll will be paid by check and the check date can be set to today or any future business day (rather than requiring ACH lead time). Payment methods cannot be changed on check-only payrolls.

Headers

X-Gusto-API-Version

string

enum

Defaults to 2026-02-01

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Allowed:

Responses

200Successful

404Not Found

422Unprocessable 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 guide for more details.