--- title: "Create a new pay schedule" method: POST path: "/v1/companies/{company_id}/pay_schedules" tags: ["Pay Schedules"] --- # Create a new pay schedule `POST /v1/companies/{company_id}/pay_schedules` If a company does not have any pay schedules, this endpoint will create a single pay schedule and assign it to all employees. This is a common use case during company onboarding. If a company has an existing active pay schedule and want to support multiple pay schedules, this endpoint will create a pay schedule that is not assigned to any employee. Be sure to **[check state laws](https://www.dol.gov/agencies/whd/state/payday)** to know what schedule is right for your customers. > 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.created`: Fires when a pay schedule is successfully created. ### Related guides - [Create a pay schedule](https://docs.gusto.com/embedded-payroll/docs/create-a-pay-schedule) - [Pay Schedules](https://docs.gusto.com/embedded-payroll/docs/pay-schedule-info) - [Manage Pay Schedules via API](https://docs.gusto.com/embedded-payroll/docs/manage-pay-schedules-api) scope: `pay_schedules:write` ## Path parameters - `company_id` string, required ## Headers - `X-Gusto-API-Version` '2026-06-15' ## Request body - PayScheduleCreateRequest — Request body for creating a pay schedule. Required when a company has no pay schedules (onboarding) or when adding an additional schedule. Be sure to [check state laws](https://www.dol.gov/agencies/whd/state/payday) to know what schedule is right for your customers. - **anchor_pay_date**: The first date that employees on this pay schedule will be paid (first company payday). - **anchor_end_of_pay_period**: The last date of the first pay period; can be the same as anchor_pay_date. - `frequency` 'Every week' | 'Every other week' | 'Twice per month' | 'Monthly', required — 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_date` string, date, required — 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, required — ISO 8601 date (YYYY-MM-DD). Required for anchor and period dates in create, update, and preview requests. - `day_1` integer, 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. On create: required for Twice per month and Monthly; omit or null for Every week and Every other week. - `day_2` integer, 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. On create: only for Twice per month; omit or null for other frequencies. - `custom_name` string, nullable — A custom pay schedule name; defaults to the pay frequency description when null or omitted. When null or omitted, the system generates a description from the pay frequency and pay days (e.g. "every 1st and 15th of the month" for twice-monthly, "every 11th of the month" for monthly, "every Friday" for weekly). The response returns this generated value in `custom_name` when no custom name was set. When provided, the value you set is stored and returned. ## Response `201` Created - 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 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_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 — 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_2` integer, 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. - `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). ## 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/revisions/826dfa57fb3b/schema)