GuidesAPI ReferenceChangelogAPI StatusAPI PolicyGusto Security
API Reference

Update a pay schedule

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

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, Gusto will automatically adjust the pay schedule to the next available pay date.

Webhooks

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

Related guides

scope: pay_schedules:write

Path Params
string
required

The UUID of the company

string
required

The UUID of the pay schedule

Body Params

Request body for updating a pay schedule. Sent in the pay_schedule_update root key. Version is required for optimistic concurrency. Pay schedules may be automatically adjusted if an onboarded company misses their first pay date; see Create a pay schedule.

When changing a flexible Twice per month schedule to Monthly, the first pay day is retained unless replaced; the second pay day and both explicit period-end days become null. Changing to Every week or Every other week clears all day fields.

string
required

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

boolean

With automatic payroll enabled, 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.

string
enum

The frequency that employees on this pay schedule are paid with Gusto. Only weekly, bi-weekly, twice per month, and monthly are supported on create and update.

  • Every week: Weekly pay.
  • Every other week: Biweekly pay.
  • Twice per month: Two pay dates per month. Provide first_pay_period_pay_day and second_pay_period_pay_day for a regular schedule, and add first_pay_period_end_day and second_pay_period_end_day for a flexible schedule. Legacy day_1/day_2 are still accepted separately. Use 31 for the last day of the month.
  • Monthly: One pay date per month; require day_1 (1-31).
Allowed:
date

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

date

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

integer | null
deprecated

Legacy field, retained unchanged for compatibility. The first pay day for Monthly and regular Twice per month schedules, or the first pay-period end day for flexible Twice per month schedules. Prefer the explicit pay-period fields. Do not combine day_1/day_2 with explicit fields in a request.

integer | null
deprecated

Legacy field, retained unchanged for compatibility. The second pay day for regular Twice per month schedules, or the second pay-period end day for flexible Twice per month schedules. A value of 31 means the last day of the month. Prefer the explicit pay-period fields. Do not combine day_1/day_2 with explicit fields in a request.

integer | null

The first pay day (1-31) for Monthly or Twice per month. For Twice per month, provide both pay-day fields together. Pay days alone configure a regular schedule; adding both explicit period-end days configures a flexible schedule. Omitted fields preserve existing values on update or persisted preview. Pay days on an existing flexible schedule cannot both be cleared. Do not mix explicit fields with day_1/day_2.

integer | null

The second pay day (1-31) for Twice per month. Provide both pay-day fields together. Pay days alone configure a regular schedule; adding both explicit period-end days configures a flexible schedule. Omitted fields preserve existing values on update or persisted preview. Pay days on an existing flexible schedule cannot both be cleared. A pay day may fall in the following month. Do not mix explicit fields with day_1/day_2.

integer | null

The last day (1-31) of the first pay period for a flexible Twice per month schedule. On create or conversion, both explicit period-end days are required. On an existing flexible schedule, omitted values are preserved and changing them requires a matching anchor_end_of_pay_period and anchor_pay_date. Do not mix explicit fields with day_1/day_2.

integer | null

The last day (1-31) of the second pay period for a flexible Twice per month schedule. A value of 31 means the last day of the month. On create or conversion, both explicit period-end days are required. On an existing flexible schedule, omitted values are preserved and changing them requires a matching anchor_end_of_pay_period and anchor_pay_date. Do not mix explicit fields with day_1/day_2.

string | null

A custom pay schedule name; null clears any custom name so the default frequency description applies.

string
enum

The day of the week that this pay schedule's workweeks start on, used for regular rate of pay overtime calculations.

Allowed:
Headers
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

Updated 5 months ago

Did this page help you?
Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 5 months ago

Did this page help you?