GuidesAPI ReferenceChangelogAPI PolicyAPI StatusGusto Security

Change a Pay Schedule and Transition Payroll

Changing pay schedules is now available for employers who wish to adjust their pay schedules. We also offer transition payrolls to account for any gaps between the old pay schedule and the new pay schedule.

1. Update 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
}
'

Previously, our Update a pay schedule endpoint only allowed updating auto pilot. We now support updating the existing pay schedule with pay_frequency, anchor_pay_date, anchor_end_of_pay_period, day_1, day_2 and custom_name parameters. Some of these fields are optional depending on the pay schedule election.

2. Get transition pay period

In the Get pay periods for a company endpoint, we introduce period_types in query params, where you can pass in a comma separated list of pay period types, such as regular, transition. If nothing is passed in, we will default to return regular pay periods.

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

3. Skip payroll

We introduced a new Skip a payroll endpoint, which supports skipping regular, new hire, termination and transition payrolls. Skipping a payroll generates a $0 payroll for the target employee(s) associated with the pay schedule. Here are some example reasons why you would want to skip a payroll:

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

Payroll Typestart_dateend_datepay_schedule_uuidemployee_uuids (only supports one employee)
RegularXXX
New HireX
TerminationX
TransitionXXX

4. Transition payroll

We added “Transition from old pay schedule” as an option for off_cycle_reason to support transition payroll through our Create an off-cycle payroll endpoint. You would need to pass in the start_date, end_date, and pay_schedule_uuid that match the transition pay period.

If the system determines there’s a gap period between the old pay schedule and the new pay schedule after the pay schedule is changed, it will prompt the user to run a transition payroll before running other payrolls in the run_payroll flow. The user will be provided with two links to either run the transition payroll or skip the transition payroll.

Please note this is a UI blocker and partners would need to implement this feature if they want to properly handle the gap period between schedules.