---
title: "Update an external payroll"
method: PUT
path: "/v1/companies/{company_uuid}/external_payrolls/{external_payroll_id}"
tags: ["External Payrolls"]
---

# Update an external payroll

`PUT /v1/companies/{company_uuid}/external_payrolls/{external_payroll_id}`

Update an external payroll with a list of external payroll items.

scope: `external_payrolls:write`

## Path parameters

- `company_uuid` string, required
- `external_payroll_id` string, required

## Headers

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

## Request body

- ExternalPayrollUpdateRequest — The request body for updating an external payroll with employee payroll items.
  - `replace_fields` boolean — Patch update external payroll items when set to true, otherwise it will overwrite the previous changes.
  - `external_payroll_items` object[], required — Payroll items for each employee in the external payroll.
    - `employee_uuid` string, uuid, required — The UUID of the employee.
    - `earnings` object[] — Earnings for the employee.
      - `earning_type` 'CompanyPayType' | 'CompanyEarningType' — The earning type class name.
      - `earning_id` integer — The ID of the earning type.
      - `amount` string, float — The earning amount in dollars.
      - `hours` string, float — The number of hours worked.
    - `benefits` object[] — Benefits for the employee.
      - `benefit_id` integer — The ID of the company benefit.
      - `company_contribution_amount` string, float — The company contribution amount in dollars.
      - `employee_deduction_amount` string, float — The employee deduction amount in dollars.
    - `taxes` object[] — Taxes for the employee.
      - `tax_id` integer — The ID of the tax.
      - `amount` string, float — The tax amount in dollars.

## Response `200`

Success

- ExternalPayroll — The representation of an external payroll.
  - `uuid` string, required — The UUID of the external payroll.
  - `company_uuid` string — The UUID of the company.
  - `check_date` string — External payroll's check date.
  - `payment_period_start_date` string — External payroll's pay period start date.
  - `payment_period_end_date` string — External payroll's pay period end date.
  - `status` 'unprocessed' | 'processed' — The status of the external payroll. The status will be `unprocessed` when the external payroll is created and transition to `processed` once tax liabilities are entered and finalized. Once in the `processed` status all actions that can edit an external payroll will be disabled.
  - `external_payroll_items` object[] — External payroll items for employees
    - `employee_uuid` string
    - `earnings` object[]
      - `amount` string, float
      - `hours` string, float
      - `earning_type` string
      - `earning_id` integer
    - `benefits` object[]
      - `benefit_id` integer
      - `company_contribution_amount` string, float
      - `employee_deduction_amount` string, float
    - `taxes` object[]
      - `tax_id` integer
      - `amount` string, float
  - `applicable_earnings` object[] — Applicable earnings based on company provisioning.
    - `earning_type` string
    - `earning_id` number
    - `name` string
    - `input_type` string
    - `category` string
  - `applicable_benefits` object[], nullable — Applicable benefits based on company provisioning.
    - `id` integer
    - `description` string
    - `active` boolean
  - `applicable_taxes` object[] — Applicable taxes based on company provisioning.
    - `id` integer
    - `name` string
    - `employer_tax` boolean — Some taxes may have an amount withheld from the employee and an amount withheld from the employer, e.g. Social Security. A `true` value indicates this is the employer's amount.
    - `resident_tax` boolean — Some taxes may have different rates or reporting requirements depending on if the employee is a resident or non-resident of the tax jurisdiction.
  - `metadata` object — Stores metadata of the external payroll.
    - `deletable` boolean — Determines if the external payroll can be deleted.

## Other responses

- `404` — Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `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/versions/826dfa57fb3b/schema)