Users can create and edit pay schedules and assign multiple pay schedules by compensation, department or per employee. We also support running transition payrolls to bridge the gap between schedule changes, which can be skipped by the user if desired.

We support managing pay schedules via Flow. Check out our Manage Pay Schedules Flow Guide for more information.

Change pay schedule

To ensure all transition payrolls are returned by the GET v1/payrolls endpoint, complete the following steps in this order.

1. Update pay schedule

Call the PUT v1/pay_schedules endpoint to update a pay schedule.

curl --request PUT \
     --url https://api.gusto-demo.com/v1/companies/company_id/pay_schedules/pay_schedule_id \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "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",
  "version": "68934a3e9455fa72420237eb05902327",
  "auto_pilot": true
}
'

Transition payrolls are not created at the time a pay schedule is changed.

2. Get transition pay period

Call the GET v1/pay_periods endpoint including the payroll_types=transition query param.

The response includes a field of payroll_type to distinguish whether the pay period is regular or transition.

3. Run transition payroll or skip payroll

Resolving transition periods is a required step in order to run payrolls again. The pay period selection and run payroll are disabled until all the transition pay periods are resolved, either through running or skipping the transition payrolls.

Follow the steps to complete a regular payroll. When you retrieve the upcoming payrolls, transition payrolls will be included in the response with "off_cycle_reason": "Transition from old pay schedule".

You can also Skip a payroll, which you might want to do if:

• There are limited funds for payrolls, but a company wants to have a consistent schedule (for the IRS)
• An employee is being onboarded but won’t be paid yet
• Company wants to skip a few months of payrolls for seasonal workers or pause payrolls entirely

Here are the parameters needed for each payroll type:

Assign multiple pay schedules

1. Create a new pay schedule

Create a new pay schedule using the POST /v1/companies/{company_uuid}/pay_schedules endpoint.

By providing a version header of X-Gusto-API-Version for 2023-06-01, users can create a new pay schedule without having any employees attached.

2. Preview

Different body parameters are required based on the pay schedule type.

A. Single

{
    "type": "single",
    "default_pay_schedule_uuid": "{{pay_schedule_uuid_1}}"
}

B. By employee

All employees in the company (onboarded or onboarding), except terminated ones, must be assigned to a pay schedule.

{
    "type": "by_employee",
    "employees": [
        {
            "employee_uuid": "{{employee_uuid_1}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_1}}"
        },
        {
            "employee_uuid": "{{employee_uuid_2}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_1}}"
        },
        {
            "employee_uuid": "{{employee_uuid_3}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_1}}"
        },
        {
            "employee_uuid": "{{employee_uuid_4}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_2}}"
        },
        {
            "employee_uuid": "{{employee_uuid_5}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_2}}"
        },
        {
            "employee_uuid": "{{employee_uuid_6}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_2}}"
        }
    ]
}

C. By department

All departments in the company must be assigned to a pay schedule. Employees without a categorized department will use the default pay schedule.

{
    "type": "by_department",
    "default_pay_schedule_uuid": "{{pay_schedule_uuid_5}}",
    "departments": [
        {
            "department_uuid": "{{employee_uuid_1}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_1}}"
        },
        {
            "department_uuid": "{{employee_uuid_2}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_3}}"
        },
        {
            "department_uuid": "{{employee_uuid_3}}",
            "pay_schedule_uuid": "{{pay_schedule_uuid_2}}"
        }
    ]
}

D. Hourly / Salaried

When choosing an hourly salaried pay schedule type, the two pay schedules must be different from each other.

{
    "type": "hourly_salaried",
    "hourly_pay_schedule_uuid": "{{pay_schedule_uuid_1}}",
    "salaried_pay_schedule_uuid": "{{pay_schedule_uuid_2}}"
}

Sample response when previewing changes

{
    "type": "by_department",
    "employee_changes": [
        {
             "employee_uuid": "311cb571-5c41-4e5b-8488-ff6a1b5a7c18",
             "first_name": "Isaiah",
             "last_name": "Berlin",
             "pay_frequency": "Monthly -- Custom monthly on the sixth",
             "first_pay_period": {
                   "pay_schedule_uuid": "fc8c8a47-74b9-492c-8fce-7907247736eb",
                   "start_date": "2023-06-07",
                   "end_date": "2023-07-06",
                   "check_date": "2023-07-06"
             },
             "transition_pay_period": null
       },
       {
            "employee_uuid": "7936c5f0-7f51-4535-aa6a-ea2ce7256fbf",
            "first_name": "Patricia",
            "last_name": "Churchland",
            "pay_frequency": "Monthly -- Custom monthly on the sixth",
            "first_pay_period": {
                 "pay_schedule_uuid": "fc8c8a47-74b9-492c-8fce-7907247736eb",
                 "start_date": "2023-06-07",
                 "end_date": "2023-07-06",
                 "check_date": "2023-07-06"
            },
            "transition_pay_period": {
                 "start_date": "2023-05-20",
                 "end_date": "2023-06-06"
            }
       }
   ]
}

This endpoint shows a preview of impacted employees’ pay schedule changes along with their transition pay periods (if applicable) and first pay period information. Users can call this endpoint multiple times and it will not make any changes to the actual data.

If the “employee_changes” is empty, that means you are updating with a pay schedule that the employees are already on. Employees remained on the same pay schedule since there was no change.

The transition pay period should be the dates between the last processed pay period’s end date to the new pay periods’ start date.

🚧

Currently, Gusto does not support update, preview or assign pay schedules when there’s a pending termination payroll for an employee. This prevents scheduled termination payroll from becoming inaccurate due to pay schedule changes.

3. Assign

Assign pay schedules using the POST /v1/companies/{company_uuid}/pay_schedules/assign endpoint.

After reviewing changes using the preview endpoint, the user can use this assign endpoint to make changes to their pay schedules.

4. Verify changes

Use the GET /v1/companies/{company_uuid}/pay_schedules/assignments endpoint to verify the pay schedule assignment for a company. Depending on the pay schedule type, it returns a pay schedule mapping with employees or departments.

The Get a company endpoint also includes a pay_schedule_type field.