Enter Historical Payrolls

Historical payrolls are used for companies who transfer from one payroll provider to your payroll product after the start of a year. It's important to capture their previous payrolls during Company Onboarding to ensure year to date filings are accurate.

Employees are expecting a single W-2 with all their tax information at the end of the calendar year even if their Employer has switched to a different payroll provider at any time during that year. Use the External Payrolls feature to collect a Company's year-to-date payroll and tax information during their initial onboarding.

This should be an optional step to complete in Company Onboarding. New businesses without any prior payroll or companies onboarding at the start of a calendar year typically do not need to enter externals and can skip this step.

The video below walks through the Gusto Flows first to give you a visual for each of the steps outlined below. The tutorial for the APIs starts around the 2min mark.

Enter Previous Payrolls

An employer will need to gather all paystubs for every employee who was paid in the current calendar year. For previous quarters in this calendar year, the employer should gather quarterly payroll summaries for each employee and use these to enter quarter-to-date ("QTD") information to simplify this step (1 payroll per calendar quarter). These summaries should include any benefits, reimbursements, or exemptions for their employees.

Employee onboarding and State Tax Setup should be completed prior to entering previous payrolls.

📘

Check date vs. Pay period

There is a difference between a check date and the pay period:

• The check date is the date the employee was paid. This date determines your payroll tax liability and will be the date you’ll enter when reporting previous payrolls.
• The pay period is the period of time during which the wages were earned. The pay period is defined by a payment_period_start_date and payment_period_end_date.

For example, if an employee worked from December 15th to December 31st and was paid on January 15th, the pay period is the December 15th - 31st and the check date is January 15th.

Create an external payroll

Use this endpoint to create the initial shell of the payroll with the check date and payment_period_start_date.

Please note: Use the last paystub issued in the quarter with a check date that precedes the last day of the quarter (i.e. 2022-03-31, 2022-06-30, 2022-09-30, 2022-12-31).

If this first request is successful, the response will include a uuid which is the external_payroll_id. This id is a unique identifier for this new external payroll and you will need this in subsequent requests.

Retrieve the external payroll using the GET an external payroll endpoint. In this call, you will be able to view the applicable_earnings, applicable_benefits, applicable_taxes for each employee. You will use these available values to update the payroll later.

You will also need to pull the employees of the company and grab the unique employee_uuid for each.

Update an External Payroll

To update a payroll, use the 'company_uuid', 'external_payroll_id' and 'employee_uuidwith associatedearnings, benefits, and taxes' for any employees who were paid on this payroll. This endpoint does support multiple employees and you can send an array of employees.

When entering the earnings for external payroll items, an Employer can enter hours or amount.

When replace_fields: true, it will do a patch to the call to update the fields based on what is passed in. If replace_fields: false, the previous information set to the payroll items will be overwritten and only keep the value passed in.

Once this payroll is successfully updated, GET tax suggestions for an external payroll to calculate applicable taxes. This will return suggested tax amounts. You can use these amounts to validate the entries provided by the end user and/or override any taxes entered. The calculation is just our guidance.

Note that GET tax suggestions for an external payroll does not update the taxes automatically on the payroll. If you wish to use the suggestions, make a call to update the external with the calculated amounts.

Repeat the steps above to allow an Employer to create and update as many external payrolls as necessary to record all year to date information for their company. A company may have several external payrolls to enter or they may only have one. It will vary by company and time of year so your application should be designed to support this.

Once the previous payrolls are entered, GET external payrolls for the company. In this response, you should see all the external payrolls entered by the employer.

Update Tax Liabilities

Retrieve the tax liabilities for the external payrolls to view the breakdown of taxes.

The tax liabilities amount is a sum of previous + current liabilities. If multiple payrolls have been added in the previous steps, the taxes from each payroll will compound on each other in order of most recent payroll to least recent. For example, if the first external added had $5 in Federal Income Tax and the second external had $7, the total will be $12.

The Employer will need to make a selection for each tax and this information will need to be sent to Gusto to record. You can make as many calls as you wish to fully update the tax liabilities.

If an Employer indicates there are no taxes outstanding ($0.00) for all taxes, Gusto will report all tax amounts as having been paid to the agency. We will still report the total wages (for all payrolls for the year - both outside of Gusto plus amounts paid by Gusto), and all the taxes owed for the year (for all payrolls outside of Gusto and tax amounts for payrolls processed by Gusto), but we won't debit or pay the taxes again for historical payrolls.

Finalize Tax Liabilities

This endpoint is used to confirm the Employer's tax liability selections. Given the sensitive nature of this information, it is important the Employer reviews the information before completing this step.

This call will convert all the external payrolls into processed payrolls and the external payrolls can no longer be edited. These payrolls will be factored into the company's tax forms (941 or 944) and the employees' W-2s.

📘

Delete an external payroll

External payrolls can be deleted if the tax liabilities have not been finalized yet.

If an external is deleted, tax liability amounts will likely change. Be sure to update the tax liabilities selections again after an external is deleted to retrieve the most recent and accurate amounts.

Once finalized, the external payroll(s) cannot be changed. To correct an external payroll, please contact Support.