GuidesAPI ReferenceChangelogAPI StatusAPI PolicyGusto Security
API Reference

Create a new pay schedule

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

If a company does not have any pay schedules, this endpoint creates a single pay schedule and assigns it to all employees (common during company onboarding).

If a company already has an active pay schedule and wants multiple pay schedules, this endpoint creates 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, the pay schedule may be automatically adjusted.

Webhooks

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

Related guides

scope: pay_schedules:write

Path Params
string
required

The UUID of the company

Body Params
string
enum
required

Pay frequency when creating or updating a schedule. Only weekly, bi-weekly, twice per month, and monthly are supported via the API.

  • 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:
date
required

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

date
required

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

integer | null

First pay day of the month (1-31).

  • Twice per month, Monthly: required.
  • Every week, Every other week: omit or null.
integer | null

Second pay day of the month (1-31); only for Twice per month.

  • Use 31 for last day of month (shorter months use the actual last day).
  • Other frequencies: omit or null.
string | null

Optional display name for the pay schedule.

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

Updated 6 days ago

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

Updated 6 days ago