Prepare a payroll for update

put

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

Prepares an unprocessed payroll for update, including: adding eligible employees to off-cycle payrolls that support multiple employees (Bonus, Correction, and Adhoc),
and updating check_date, payroll_deadline, and payroll_status_meta dates and times.

Use this endpoint before calling PUT /v1/companies/{company_id}/payrolls/{payroll_id}.

Notes

Nullifies calculated_at and totals if the payroll was previously calculated
Returns the version parameter required for updating the payroll
employees:read scope is required to include employee compensations data in the response.
Results are paginated, with a maximum page size of 100 employee compensations.

scope: payrolls:write employees:read

Path Params

company_id

string

required

The UUID of the company

payroll_id

string

required

The UUID of the payroll

Query Params

page

integer

The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.

per

integer

Number of objects per page. For majority of endpoints will default to 25

sort_by

string

^(first_name|last_name)(:(asc|desc))?(,(first_name|last_name)(:(asc|desc))?)*$

Sort employee compensations by one or more fields. Options: first_name, last_name. Append :asc or :desc to specify direction (e.g., last_name:asc or last_name:asc,first_name:asc). Defaults to ascending.

Body Params

employee_uuids

array of strings | null

The employees to prepare, identified by UUID. If omitted, every employee currently on the payroll is prepared.

Off-cycle payrolls that support multiple employees (Bonus, Correction, Adhoc): passing employee_uuids also adds eligible employees who aren't yet on the payroll - a listed employee not on the payroll is added, while one already on it is simply prepared. A request may include up to 100 UUIDs, of which at most 25 may be employees not already on the payroll; an ineligible or unknown UUID, or more than 25 new employees, is rejected with a 422.

All other payrolls: employee_uuids selects which of the payroll's existing employees to prepare; a UUID for an employee not on the payroll is rejected with a 422.

employee_uuids

Headers

X-Gusto-API-Version

string

enum

Defaults to 2026-06-15

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

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

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.