Cancel a payroll

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

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 3:30pm PT on the payroll_deadline

scope: payrolls:run

Responses

Response body

object

payroll_deadline

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

The date at which the payroll was processed. Null if the payroll isn't processed yet.

calculated_at

string

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

string | null

The off-cycle reason. Only included for off-cycle payrolls.

Benefit reversal Bonus Correction Dismissed employee Hired employee Wage correction Tax reconciliation Reversal Disability insurance distribution Transition from old pay schedule

auto_pilot

boolean

Indicates whether the payroll is an auto pilot payroll

external

boolean

Indicates whether the payroll is an external payroll

final_termination_payroll

boolean

Indicates whether the payroll is the final payroll for a terminated employee. Only included for off-cycle payrolls.

withholding_pay_period

string

The payment schedule tax rate the payroll is based on. Only included for off-cycle payrolls.

Every week Every other week Twice per month Monthly Quarterly Semiannually Annually

skip_regular_deductions

boolean

Block regular deductions and contributions for this payroll. Only included for off-cycle payrolls.

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. Only included for off-cycle payrolls.

pay_period

object

start_date

string

The start date, inclusive, of the pay period.

end_date

string

The start date, inclusive, of the pay period.

pay_schedule_uuid

string | null

The UUID of the pay schedule for the payroll.

payroll_status_meta

object

Information about the payroll's status and expected dates

cancellable

boolean

true if the payroll may be cancelled.

expected_check_date

string

The date an employee will be paid if the payroll is submitted now.

initial_check_date

string

The normal check date for the associated pay period.

expected_debit_time

string

The time the employer's account will be debited if the payroll is submitted now.

payroll_late

boolean

expected_check_date > initial_check_date.

initial_debit_cutoff_time

string

Payroll must be submitted at or before this time to avoid late payroll.

totals

object

The subtotals for the payroll.

company_debit

string

The total company debit for the payroll.

net_pay_debit

string

length ≥ 1

The total company net pay for the payroll.

tax_debit

string

The total tax debit for the payroll.

reimbursement_debit

string

The total reimbursement debit for the payroll.

child_support_debit

string

The total child support debit for the payroll.

reimbursements

string

The total reimbursements for the payroll.

net_pay

string

The net pay amount for the payroll.

gross_pay

string

The gross pay amount for the payroll.

employee_bonuses

string

The total employee bonuses amount for the payroll.

employee_commissions

string

The total employee commissions amount for the payroll.

employee_cash_tips

string

The total employee cash tips amount for the payroll.

employee_paycheck_tips

string

The total employee paycheck tips amount for the payroll.

additional_earnings

string

The total additional earnings amount for the payroll.

owners_draw

string

The total owner's draw for the payroll.

check_amount

string

The total check amount for the payroll.

employer_taxes

string

The total amount of employer paid taxes for the payroll.

employee_taxes

string

The total amount of employee paid taxes for the payroll.

benefits

string

The total amount of company contributed benefits for the payroll.

employee_benefits_deductions

string

The total amount of employee deducted benefits for the payroll.

imputed_pay

string

The total amount of imputed pay for the payroll.

deferred_payroll_taxes

string

The total amount of payroll taxes deferred for the payroll, such as allowed by the CARES act.

other_deductions

string

The total amount of deductions for the payroll.

employee_compensations

array of objects

employee_compensations

object

employee_uuid

string

The UUID of the employee.

excluded

boolean

This employee will be excluded (skipped) from payroll calculation and will not be paid for the payroll. Cancelling a payroll would reset all employees' excluded back to false.

version

string

The current version of this employee compensation. This field is only available for prepared payrolls. See the versioning guide for information on how to use this field.

gross_pay

number | null

The employee's gross pay, equal to regular wages + cash tips + payroll tips + any other additional earnings, excluding imputed income. This value is only available for processed payrolls.

net_pay

number | null

The employee's net pay, equal to gross_pay - employee taxes - employee deductions or garnishments - cash tips. This value is only available for processed payrolls.

check_amount

number | null

The employee's check amount, equal to net_pay + reimbursements. This value is only available for processed payrolls.

payment_method

string | null

The employee's compensation payment method.

Check Direct Deposit

memo

string | null

Custom text that will be printed as a personal note to the employee on a paystub.

fixed_compensations

array of objects

An array of fixed compensations for the employee. Fixed compensations include tips, bonuses, and one time reimbursements. If this payroll has been processed, only fixed compensations with a value greater than 0.00 are returned. For an unprocessed payroll, all active fixed compensations are returned.

fixed_compensations

object

name

string

The name of the compensation. This also serves as the unique, immutable identifier for this compensation.

amount

string

The amount of the compensation for the pay period.

job_uuid

string

The UUID of the job for the compensation.

hourly_compensations

array of objects

An array of hourly compensations for the employee. Hourly compensations include regular, overtime, and double overtime hours. If this payroll has been processed, only hourly compensations with a value greater than 0.00 are returned. For an unprocessed payroll, all active hourly compensations are returned.

hourly_compensations

object

name

string

The name of the compensation. This also serves as the unique, immutable identifier for this compensation.

hours

string

The number of hours to be compensated for this pay period.

amount

string

The amount of the compensation. This field is only available after the payroll is calculated and cannot be used for updating hourly compensations.

job_uuid

string

The UUID of the job for the compensation.

compensation_multiplier

number

The amount multiplied by the base rate to calculate total compensation per hour worked.

flsa_status

string

The FLSA Status of the employee's primary job compensation

paid_time_off

array of objects

An array of all paid time off the employee is eligible for this pay period.

paid_time_off

object

name

string

The name of the PTO. This also serves as the unique, immutable identifier for the PTO.

hours

string

The hours of this PTO taken during the pay period.

final_payout_unused_hours_input

string

The outstanding hours paid upon termination. This field is only applicable for termination payrolls.

benefits

array of objects

An array of employee benefits for the pay period. Benefits are only included for processed payroll when the include parameter is present.

benefits

object

name

string

employee_deduction

number

company_contribution

number

imputed

boolean

deductions

array of objects

An array of employee deductions for the pay period. Deductions are only included for processed payroll when the include parameter is present.

deductions

object

name

string

amount

number

taxes

array of objects

An array of employer and employee taxes for the pay period. Only included for processed or calculated payrolls when taxes is present in the include parameter.

taxes

object

name

string

required

length ≥ 1

employer

boolean

required

amount

number

required

company_taxes

array of objects

An array of taxes applicable to this payroll in addition to taxes included in employee_compensations. Only included for processed or calculated payrolls when taxes is present in the include parameter.

company_taxes

object

name

string

The tax name

employer

boolean

Whether this tax is an employer or employee tax

amount

string

The amount of this tax for the payroll

payment_speed_changed

object

Only applicable when a payroll is moved to four day processing instead of fast ach.

original_check_date

string

Original check date when fast ach applies.

current_check_date

string

Current check date.

original_debit_date

string

Original debit date when fast ach applies.

current_debit_date

string

Current debit date.

reason

string

The reason why the payroll is moved to four day.

created_at

date-time

Datetime for when the resource was created.

submission_blockers

array of objects

Only included for processed or calculated payrolls

submission_blockers

object

blocker_type

string

The type of blocker that's blocking the payment submission.

blocker_name

string

The name of the submission blocker.

unblock_options

array of objects

The available options to unblock a submission blocker.

unblock_options

object

unblock_type

string

The type of unblock option for the submission blocker.

check_date

string

The payment check date associated with the unblock option.

metadata

object

Additional data associated with the unblock option.

Has additional fields

selected_option

string | null

The unblock option that's been selected to resolve the submission blocker.

status

string

The status of the submission blocker.

unresolved resolved

credit_blockers

array of objects

Only included for processed payrolls

credit_blockers

object

blocker_type

string

The type of blocker that's blocking the payment from being credited.

blocker_name

string

The name of the credit blocker.

unblock_options

array of objects

The available options to unblock a credit blocker.

unblock_options

object

unblock_type

string

The type of unblock option for the credit blocker.

check_date

string

The payment check date associated with the unblock option.

metadata

object

Additional data associated with the unblock option.

Has additional fields

selected_option

string | null

The unblock option that's been selected to resolve the credit blocker.

status

string

The status of the credit blocker

unresolved pending_review resolved failed

processing_request

object | null

status

string

The status of the payroll processing request

calculating calculate_success submitting submit_success processing_failed

errors

array of objects

Errors that occurred during async payroll processing

errors

object

error_key

string

Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error.

`invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the Errors Categories guide for more details.

xxxxxxxxxx
curl --request PUT \
     --url https://api.gusto-demo.com/v1/companies/company_id/payrolls/payroll_id/cancel \
     --header 'X-Gusto-API-Version: 2024-03-01' \
     --header 'accept: application/json'

xxxxxxxxxx
}
{
  "payroll_deadline": "2021-02-18T22:00:00Z",
  "check_date": "2021-02-22",
  "off_cycle": false,
  "external": false,
  "auto_pilot": false,
  "processed": false,
  "processed_date": null,
  "calculated_at": null,
  "uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",
  "payroll_uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",
  "company_uuid": "6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb",
  "created_at": "2022-02-01T22:00:00Z",
  "pay_period": {
    "start_date": "2021-02-01",
    "end_date": "2021-02-15",
    "pay_schedule_uuid": "00ebc4a4-ec88-4435-8f45-c505bb63e501"
  },
  "payroll_status_meta": {
    "cancellable": false,
    "expected_check_date": "2021-02-22",
    "initial_check_date": "2021-02-22",
    "expected_debit_time": "2021-02-18T22:00:00Z",
    "payroll_late": false,
    "initial_debit_cutoff_time": "2021-02-18T22:00:00Z"

200Example response

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.

`invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the Errors Categories guide for more details.