Regular Payroll

Your embedded payroll product allows the Company to pay the Employees the right amount at the right cadence, while accounting for tax implications.

The instructions below assume that the application is already authenticated, and that the bearer token is being specified via the Authorization HTTP header.

Video Tutorial

Step-by-Step Instructions

The pay_schedule object in Gusto API includes details of when employees work and when they should be paid. It establishes pay periods with start_date and end_date. We automatically pre-generate scheduled regular payrolls based on the company’s pay schedule and corresponding pay periods. Pay periods are the foundation of payroll. Compensation, time & attendance, taxes, and expense reports all rely on when they happened. To begin submitting information for a given payroll, we need to agree on the time period.

To run a regular payroll, start by selecting an open pay period. Upcoming regular payrolls can be retrieved through a GET request to the get all payrolls for a company endpoint and the next upcoming payroll will be the earliest unprocessed payroll. Use the optional parameters to narrow down the response (e.g processed = false).

To input hours and earnings to the upcoming payroll, use the update a payroll endpoint. Key inputs include hours (regular, overtime, double overtime), earnings (salaries, bonuses, commissions, tips, reimbursements, or custom earnings), and time off (vacation, sick, holiday).

The payrolls are identified by their pay periods’ start_date and end_date. Both are required and must correspond with an existing, unprocessed payroll. If the dates do not match, the entire request will be rejected. A step-by-step guide to update the unprocessed payroll initially is available here.

Example UI for this first step:

A payroll must first be updated with the update a payroll API to create a unique ID for the payroll.

This payroll_id can then be used to:

1. Get a single payroll by ID
2. Update a payroll by ID
3. Calculate a payroll
4. Submit payroll
5. Cancel a payroll

These 5 type of requests cannot be completed without a payroll_id.

Once a payroll is updated, call the calculate a payroll endpoint. This performs calculations for taxes, benefits, and deductions for an unprocessed payroll. The calculated payroll details provide a preview of the actual values that will be used when the payroll is run. Any benefits or deductions - mandatory or voluntary - that are set up for the employee at the time payroll is calculated will automatically be factored in.

📘

Calculate a Payroll

• This endpoint is asynchronous and responds with only a 202 HTTP status. To view the details of the calculated payroll, use the [GET a single payroll by ID](LINK-get-a-payroll-by-id] endpoint with the show_calculation and includes parameters.
• Due to the complex calculations of payroll, please allow up to ~15 seconds for the calculation to complete.

We recommend building a UI where the user can review their payroll before submitting. The displayed information can be customized to fit your unique business needs, but we highly recommend a preview step to provide the user with the payroll details before they finalize it. Typically this includes a breakdown of taxes and debits, similar to the one below:

If everything looks accurate, a payroll can be processed with a request to the submit payroll endpoint (example #2 above). Upon success, this request transitions the payroll to the processed state and initiates the transfer of funds.

This is a critical step to process payroll. A payroll is not finalized without calling this endpoint.

Cancel a Payroll

In some cases, a payroll may be submitted with incorrect payroll information. A request to the cancel a payroll endpoint will cancel the specified payroll. This request transitions a processed payroll back to the unprocessed state.

❗️

Important

A payroll cannot be canceled after 3:30pm PT on the payroll_deadline. If a customer needs to cancel a payroll after this time frame they will need to contact support.