---
title: "Prepare a payroll for update"
method: PUT
path: "/v1/companies/{company_id}/payrolls/{payroll_id}/prepare"
tags: ["Payrolls"]
---

# Prepare a payroll for update

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

Prepares an unprocessed payroll for update, including: adding or removing eligible employees from the payroll,
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}](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls).

### Notes

* Nullifies `calculated_at` and `totals` if the payroll was previously calculated
* Returns the `version` parameter required for [updating the payroll](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls)
* `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 parameters

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

## Query parameters

- `page` integer
- `per` integer
- `sort_by` string

## Headers

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

## Request body

- object
  - `employee_uuids` string[], nullable — An array of employee UUIDs. If passed, only those employees payroll items will be prepared.

## Response `200`

Successful

- PayrollPrepared — The response from preparing a payroll for update. Contains refreshed employee compensations, updated payroll dates, and version information needed for subsequent payroll updates.
  - `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
  - `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` 'Every week' | 'Every other week' | 'Twice per month' | 'Monthly' | 'Quarterly' | 'Semiannually' | 'Annually', nullable — The payment schedule tax rate the payroll is based on. Only included for off-cycle payrolls.
  - `skip_regular_deductions` boolean, nullable — Block regular deductions and contributions for this payroll. Only included for off-cycle payrolls.
  - `fixed_withholding_rate` boolean, nullable — 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` PayrollPayPeriodType
    - `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, nullable — The UUID of the pay schedule for the payroll.
  - `payroll_status_meta` PayrollPayrollStatusMetaType — 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, nullable — The normal check date for the associated pay period. Returns `null` for off-cycle payrolls (not meaningful for off-cycle).
    - `expected_debit_time` string — The time the employer's account will be debited if the payroll is submitted now.
    - `payroll_late` boolean, nullable — expected_check_date > initial_check_date. Returns `null` for off-cycle payrolls (not meaningful for off-cycle).
    - `initial_debit_cutoff_time` string — Payroll must be submitted at or before this time to avoid late payroll.
  - `employee_compensations` PayrollEmployeeCompensationsType[]
    - `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.
    - `first_name` string, nullable — The first name of the employee. Requires `employees:read` scope.
    - `preferred_first_name` string, nullable — The preferred first name of the employee. Requires `employees:read` scope.
    - `last_name` string, nullable — The last name of the employee. Requires `employees:read` scope.
    - `gross_pay` string, nullable — The employee's gross pay (as a string-formatted decimal, e.g. "1234.56"), 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` string, nullable — The employee's net pay (as a string-formatted decimal, e.g. "1234.56"), equal to gross_pay - employee taxes - employee deductions or garnishments - cash tips. This value is only available for processed payrolls.
    - `check_amount` string, nullable — The employee's check amount (as a string-formatted decimal, e.g. "1234.56"), equal to net_pay + reimbursements. This value is only available for processed payrolls.
    - `payment_method` 'Direct Deposit' | 'Check' | 'Historical', nullable — The employee's compensation payment method. Is *only* `Historical` when retrieving external payrolls initially run outside of Gusto, then put into Gusto.
    - `memo` string, nullable — Custom text that will be printed as a personal note to the employee on a paystub.
    - `fixed_compensations` object[] — An array of fixed compensations for the employee. Fixed compensations include tips and bonuses. On regular payrolls, reimbursements are sent via the dedicated `reimbursements` array instead. Off-cycle payrolls continue to include reimbursements in `fixed_compensations`. 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.
      - `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` object[] — 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.
      - `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` object[] — An array of all paid time off the employee is eligible for this pay period.
      - `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.
      - `amount` string, nullable — The dollar amount paid for this PTO entry during the pay period (as a string-formatted decimal, e.g. "1234.56"). Only available for processed payrolls.
      - `final_payout_unused_hours_input` string, nullable — The outstanding hours paid upon termination. This field is only applicable for termination payrolls.
    - `reimbursements` object[] — An array of reimbursements for the employee.
      - `amount` string, required — The dollar amount of the reimbursement for the pay period.
      - `description` string, nullable, required — The description of the reimbursement. Null for unnamed reimbursements.
      - `uuid` string, nullable — The UUID of the reimbursement. Null for unnamed reimbursements. This field is only available for unprocessed payrolls.
      - `recurring` boolean — Whether the reimbursement is recurring. This field is only available for unprocessed payrolls.
    - `custom_withholdings` object — The one-time custom withholding overrides applied to this payroll for this employee. `federal` is null when no federal one-time override is set; `state` is an empty array when no state one-time overrides are set.
      - `federal` object, nullable — Federal one-time custom withholding override applied to this payroll.
        - `override_type` 'one_time' — Override mode. Only `one_time` is currently exposed.
        - `amount` string — The amount that was withheld for this payroll.
        - `amount_type` 'fixed' | 'percent' — How to interpret the amount.
      - `state` object[] — State one-time custom withholding overrides applied to this payroll, one entry per state field.
        - `employee_state_field_uuid` string — The UUID of the EmployeeStateField this withholding applies to.
        - `override_type` 'one_time' — Override mode. Only `one_time` is currently exposed.
        - `amount` string — The amount that was withheld for this payroll.
        - `amount_type` 'fixed' | 'percent' — How to interpret the amount.
    - `version` string — The current version of this employee compensation. This field is only available for prepared payrolls. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field.
    - `deductions` object[] — An array of deductions for the employee. This field is included by default for regular payrolls in version `v2025-06-15` and later.
      - `name` string — The name of the deduction.
      - `amount` number — The amount of the deduction for the pay period.
      - `amount_type` 'fixed' | 'percent' — The amount type of the deduction for the pay period. Only present for unprocessed payrolls.
      - `uuid` string — The UUID of the deduction. Only present for unprocessed payrolls.
      - `updatable_via_payroll` boolean — Whether the deduction can be updated via the payroll update endpoint. Only present for unprocessed payrolls.
  - `payment_speed_changed` PayrollPaymentSpeedChangedType — 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` string, date-time — Datetime for when the resource was created.
  - `fixed_compensation_types` object[]
    - `name` string — The name of an available type of fixed compensation.
  - `processing_request` PayrollProcessingRequest, nullable
    - `status` 'calculating' | 'calculate_success' | 'submitting' | 'submit_success' | 'processing_failed' — The status of the payroll processing request
    - `errors` EntityErrorObject[] — Errors that occurred during async payroll processing
      - `error_key` string, required — Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error.
      - `category` 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.
      - `message` string — Provides details about the error - generally this message can be surfaced to an end user.
      - `metadata` union — 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.
        - object — multiple entities
          - `entities` MetadataWithOneEntity[], required
            - `entity_type` string — Name of the entity that the error corresponds to.
            - `entity_uuid` string — Unique identifier for the entity.
            - `valid_from` string, nullable
            - `valid_up_to` string, nullable
            - `key` string, nullable
            - `state` string, nullable
        - object — single entity
          - `entity_type` string — Name of the entity that the error corresponds to.
          - `entity_uuid` string — Unique identifier for the entity.
          - `valid_from` string, nullable
          - `valid_up_to` string, nullable
          - `key` string, nullable
          - `state` string, nullable
      - `errors` object[] — Will only exist if category is `nested_errors`. It is possible to have multiple levels of nested errors.
        - `error_key` string — Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error.
        - `category` 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.
        - `message` 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.
  - `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.

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)