--- title: "Update a pay schedule" method: PUT path: "/v1/companies/{company_id}/pay_schedules/{pay_schedule_id}" tags: ["Pay Schedules"] --- # Update a pay schedule `PUT /v1/companies/{company_id}/pay_schedules/{pay_schedule_id}` ## Request - Base URL: `https://api.gusto-demo.com` - URL: `https://api.gusto-demo.com/v1/companies/{company_id}/pay_schedules/{pay_schedule_id}` - Auth: HTTP bearer Updates a pay schedule. The `version` parameter from the GET response is required for [optimistic concurrency](doc:api-fundamentals); 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 - [Create a pay schedule](doc:create-a-pay-schedule) - [Manage Pay Schedules via API](doc:manage-pay-schedules-api) scope: `pay_schedules:write` ## Path parameters - `company_id` string, required - `pay_schedule_id` string, required ## Headers - `X-Gusto-API-Version` '2026-06-15' ## Request body - PayScheduleUpdateRequest: 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](https://docs.gusto.com/embedded-payroll/docs/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. - `version` string, required: Current version of the pay schedule from the GET response; required for optimistic concurrency. Mismatch returns 409 Conflict. - `auto_payroll` 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. - `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. 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). - `anchor_pay_date` string, date: ISO 8601 date (YYYY-MM-DD). Required for anchor and period dates in create, update, and preview requests. - `anchor_end_of_pay_period` string, date: ISO 8601 date (YYYY-MM-DD). Required for anchor and period dates in create, update, and preview requests. - `day_1` integer, nullable: 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. - `day_2` integer, nullable: 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. - `first_pay_period_pay_day` integer, nullable: 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. - `second_pay_period_pay_day` integer, nullable: 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. - `first_pay_period_end_day` integer, nullable: 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. - `second_pay_period_end_day` integer, nullable: 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. - `custom_name` string, nullable: A custom pay schedule name; null clears any custom name so the default frequency description applies. - `workweek_start_day` 'Sunday' | 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday': The day of the week that this pay schedule's workweeks start on, used for regular rate of pay overtime calculations. ## Response `200` Successful - PayScheduleShow: Pay schedule returned from pay schedule endpoints (GET by ID, POST create, PUT update). Same fields as Pay-Schedule with a required `version` for [optimistic concurrency](https://docs.gusto.com/embedded-payroll/docs/api-fundamentals#optimistic-version-control). For API version 2025-11-15 and later, responses use `auto_payroll`; earlier versions use `auto_pilot` for the same semantic. - `uuid` string, required: The unique identifier of the pay schedule in Gusto. - `version` string, required: The current version of the pay schedule. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/api-fundamentals#optimistic-version-control) for information on how to use this field for optimistic concurrency. - `frequency` 'Every week' | 'Every other week' | 'Twice per month' | 'Monthly' | 'Quarterly' | 'Annually': 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 twice per month. The explicit pay-day fields always represent pay days; explicit period-end fields are populated only for flexible schedules. Legacy day_1/day_2 retain their historical values. - `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_date` string, date: The first date that employees on this pay schedule are paid with Gusto (ISO 8601 YYYY-MM-DD). - `anchor_end_of_pay_period` string, 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_1` integer, nullable: 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. - `day_2` integer, nullable: 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. - `first_pay_period_pay_day` integer, nullable: The first pay day of the month (1-31) for Monthly and Twice per month schedules; null for other frequencies. For flexible schedules, this is independent of first_pay_period_end_day. A pay day may fall in the following month. - `second_pay_period_pay_day` integer, nullable: The second pay day of the month (1-31) for Twice per month schedules; null for other frequencies. For flexible schedules, this is independent of second_pay_period_end_day. A value of 31 means the last day of the month; a pay day may fall in the following month. - `first_pay_period_end_day` integer, nullable: The last day (1-31) of the first pay period for a flexible Twice per month schedule; null for regular schedules and other frequencies. - `second_pay_period_end_day` integer, nullable: The last day (1-31) of the second pay period for a flexible Twice per month schedule; null for regular schedules and other frequencies. A value of 31 means the last day of the month. - `name` string, 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_name` string: 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_payroll` boolean: 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. - `active` boolean: Whether this pay schedule is associated with any employees. A pay schedule is inactive when it's unassigned. - `auto_payroll_enablement_blockers` PayScheduleAutoPayrollEnablementBlocker[], nullable: List of blockers preventing automatic payroll from being enabled. If automatic payroll is already enabled, this field is null. - `key` string: The blocker type. Possible values: employees_not_on_direct_deposit, employees_not_salaried, missing_state_tax_requirements, missing_funding_method, one_day_ach_speed_not_supported, company_suspended, earned_fast_ach_not_met, hourly_employees_missing_default_hours. - `metadata` object: Blocker-specific metadata (e.g. employee_uuids, states). - `workweek_start_day` 'Sunday' | 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday', nullable: The day of the week that this pay schedule's workweeks start on, used for regular rate of pay overtime calculations. Null when no workweek start day has been configured (e.g. legacy pay schedules). ## Other responses - `404`: Not Found The requested resource does not exist. Make sure the provided UUID is valid. - `409`: Conflict - `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. ## Changes - **2026-11-03** `f98575fa2a5e`: 14 info - added the new optional request property `first_pay_period_end_day` - added the new optional request property `first_pay_period_pay_day` - added the new optional request property `second_pay_period_end_day` - added the new optional request property `second_pay_period_pay_day` - …10 more [Operation history](https://skmtc.dev/gusto/apis/gusto-api/changes/v1/companies/:company_id/pay_schedules/:pay_schedule_id/put.md) --- [API](https://skmtc.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)