Create a new pay schedule

post

https://api.gusto-demo.com/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 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

scope: pay_schedules:write

Path Params

company_id

string

required

The UUID of the company

Body Params

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 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

string

enum

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).

Allowed:

anchor_pay_date

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

date

required

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

day_1

integer | null

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 | null

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 | null

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.

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

201Created

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

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.