Update a pay schedule

put

https://api.gusto-demo.com/v1/companies/{company_id}/pay_schedules/{pay_schedule_id}

Updates a pay schedule. The version parameter from the GET response is required for optimistic concurrency; a mismatch returns 409 Conflict.

Effect on payrolls

Updating a pay schedule will delete any unprocessed regular payrolls whose pay period end date is today or in the future. Already-processed payrolls are not affected.

Pay schedules may be automatically adjusted

If an onboarded company misses their first pay date, the pay schedule may be automatically adjusted.

Webhooks

pay_schedule.updated: Fires when a pay schedule is successfully updated.

Related guides

scope: pay_schedules:write

Path Params

company_id

string

required

The UUID of the company

pay_schedule_id

string

required

The UUID of the pay schedule

Body Params

version

string

required

Current version of the pay schedule from the GET response; required for optimistic concurrency. Mismatch returns 409 Conflict.

auto_payroll

boolean

When true, Autopayroll is enabled and payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically and must be run manually. For API versions before 2025-11-15 the request field is auto_pilot.

frequency

string

enum

Pay frequency when creating or updating a schedule. Only weekly, bi-weekly, twice per month, and monthly are supported via the API.

Every week: Weekly pay.
Every other week: Biweekly pay.
Twice per month: Two pay dates per month; require day_1 and day_2 (use 31 for last day of month).
Monthly: One pay date per month; require day_1 (1-31).

Allowed:

anchor_pay_date

date

ISO 8601 date (YYYY-MM-DD). Required for anchor and period dates in create, update, and preview requests.

anchor_end_of_pay_period

date

ISO 8601 date (YYYY-MM-DD). Required for anchor and period dates in create, update, and preview requests.

day_1

integer | null

First pay day of the month (1–31). Required for Twice per month and Monthly; null for Every week and Every other week.

day_2

integer | null

Second pay day of the month (1–31); only for Twice per month. Use 31 for last day of month. Null for other frequencies.

custom_name

string | null

Custom name for the pay schedule; null clears it.

Headers

X-Gusto-API-Version

string

enum

Defaults to 2026-02-01

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

200Successful

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

409Conflict

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.