GuidesAPI ReferenceChangelogAPI PolicyAPI StatusGusto Security
API Reference
Start typing to search…
v2023-09-01 is in the deprecation process and all prior versions have been deprecated. Click this banner to review our version upgrade guide.

Update a payroll by ID

put https://api.gusto-demo.com/v1/companies//payrolls/

This endpoint allows you to update information for one or more employees for a specific unprocessed payroll. You can think of the unprocessed
payroll object as a template of fields that you can update. You cannot modify the structure of the payroll object through this endpoint, only values
of the fields included in the payroll. If you do not include specific employee compensations or fixed/hourly compensations in your request body, they
will not be removed from the payroll.

scope: payrolls:write

Path Params
string
required

The UUID of the company

string
required

The UUID of the payroll

Body Params
employee_compensations
array of objects
required
employee_compensations*
string

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

boolean

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

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

Headers
string
Defaults to 2024-04-01

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

Responses

Response body
object
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.

string

The date on which employees will be paid for the payroll.

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.

string

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

string

A timestamp of the last valid payroll calculation. Null if there isn't a valid calculation.

string

The UUID of the payroll.

string

The UUID of the payroll.

string

The UUID of the company for the payroll.

boolean

Indicates whether the payroll is an off-cycle payroll

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

boolean

Indicates whether the payroll is an auto pilot payroll

boolean

Indicates whether the payroll is an external payroll

boolean

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

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

boolean

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

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
string

The start date, inclusive, of the pay period.

string

The start date, inclusive, of the pay period.

string | null

The UUID of the pay schedule for the payroll.

payroll_status_meta
object

Information about the payroll's status and expected dates

boolean

true if the payroll may be cancelled.

string

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

string

The normal check date for the associated pay period.

string

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

boolean

expected_check_date > initial_check_date.

string

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

employee_compensations
array of objects
employee_compensations
object
string

The UUID of the employee.

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.

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.

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.

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.

number | null

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

string | null

The employee's compensation payment method.

Check Direct Deposit

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
string

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

string

The amount of the compensation for the pay period.

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
string

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

string

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

string

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

string

The UUID of the job for the compensation.

number

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

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
string

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

string

The hours of this PTO taken during the pay period.

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
string
number
number
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
string
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
string
required
length ≥ 1
boolean
required
number
required
payment_speed_changed
object

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

string

Original check date when fast ach applies.

string

Current check date.

string

Original debit date when fast ach applies.

string

Current debit date.

string

The reason why the payroll is moved to four day.

date-time

Datetime for when the resource was created.

fixed_compensation_types
array of objects
fixed_compensation_types
object
string

The name of an available type of fixed compensation.

object | null
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
string
required

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

string
required

Specifies the type of error. The category provides error groupings and can be used to build custom error handling in your integration. If category is nested_errors, the object will contain a nested errors property with entity errors.

string

Provides details about the error - generally this message can be surfaced to an end user.

metadata
object

Contains relevant data to identify the resource in question when applicable. For example, to identify an entity entity_type and entity_uuid will be provided.

errors
array of objects

Will only exist if category is nested_errors. It is possible to have multiple levels of nested errors.

errors
object
string

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

string

Specifies the type of error. The category provides error groupings and can be used to build custom error handling in your integration. If category is nested_errors, the object will contain a nested errors property with entity errors.

string

Provides details about the error - generally this message can be surfaced to an end user.

metadata
object

Contains relevant data to identify the resource in question when applicable. For example, to identify an entity entity_type and entity_uuid will be provided.

Has additional fields
404

Not Found

The requested resource does not exist. Make sure the provided UUID is valid.

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

Updated over 1 year ago

Did this page help you?
Language
Credentials

Updated over 1 year ago

Did this page help you?