v1

latestOpenAPI 3.1.02026-07-243113441.2 MB

Pay Schedules

Update a pay schedule

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

put/v1/companies/{company_id}/pay_schedules/{pay_schedule_id}

Path parameters

company_idstring required

The UUID of the company

pay_schedule_idstring required

The UUID of the pay schedule

Headers

X-Gusto-API-Version'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.

Request body

versionstring required

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

auto_payrollboolean

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.

frequency'Every week' | 'Every other week' | 'Twice per month' | 'Monthly'

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; require day_1 and day_2 (use 31 for last day of month).
Monthly: One pay date per month; require day_1 (1-31).

anchor_pay_datestring date

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

anchor_end_of_pay_periodstring date

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

day_1integer nullable

An integer between 1 and 31 indicating the first day of the month that employees are paid. This field is only relevant for pay schedules with the "Twice per month" and "Monthly" frequencies. It will be null for pay schedules with other frequencies.

day_2integer nullable

An integer between 1 and 31 indicating the second day of the month that employees are paid. This field is the second pay date for pay schedules with the "Twice per month" frequency. For semi-monthly pay schedules, set this field to 31. For months shorter than 31 days, the second pay date is set to the last day of the month. It will be null for pay schedules with other frequencies.

custom_namestring nullable

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

Example request

{
  "version": "68934a3e9455fa72420237eb05902327",
  "auto_payroll": true,
  "frequency": "Twice per month",
  "anchor_pay_date": "2021-10-15",
  "anchor_end_of_pay_period": "2021-10-15",
  "day_1": 15,
  "day_2": 31,
  "custom_name": "demo pay schedule"
}

Response

Successful

uuidstring required

The unique identifier of the pay schedule in Gusto.

versionstring required

The current version of the pay schedule. See the versioning guide for information on how to use this field for optimistic concurrency.

The frequency that employees on this pay schedule are paid with Gusto.

READ-ONLY in responses. Possible values:

Every week: Employees are paid weekly.
Every other week: Employees are paid bi-weekly (every two weeks).
Twice per month: Employees are paid on two fixed days each month (e.g. 1st and 15th); use day_1 and day_2.
Monthly: Employees are paid once per month; use day_1 for the pay day.
Quarterly: Employees are paid every three months.
Annually: Employees are paid once per year.

anchor_pay_datestring date

The first date that employees on this pay schedule are paid with Gusto (ISO 8601 YYYY-MM-DD).

anchor_end_of_pay_periodstring date

The last date of the first pay period. This can be the same date as the anchor pay date (ISO 8601 YYYY-MM-DD).

day_1integer nullable

day_2integer nullable

An integer between 1 and 31 indicating the second day of the month that employees are paid. This field is the second pay date for pay schedules with the "Twice per month" frequency. For semi-monthly pay schedules, this field should be set to 31. For months shorter than 31 days, the second pay date is set to the last day of the month. It will be null for pay schedules with other frequencies.

namestring nullable

This field will be hourly when the pay schedule is for hourly employees, salaried when the pay schedule is for salaried employees, the department name if pay schedule is by department, and null when the pay schedule is for all employees.

custom_namestring

A custom name for a pay schedule; defaults to the pay frequency description when none was set by the partner.

When the partner never set a custom name (or cleared it), this field contains the auto-generated description derived from frequency and pay days (e.g. "every 1st and 15th of the month", "every Friday"). When the partner set a custom name on create or update, this field contains that value.

auto_payrollboolean

With automatic payroll enabled, payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically. Returned for API version 2025-11-15 and later; for earlier versions the response uses auto_pilot instead.

activeboolean

Whether this pay schedule is associated with any employees. A pay schedule is inactive when it's unassigned.