Complete a 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.
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.
Before using this guide you need a fully onboarded Company and Employee.
1. Retrieve Upcoming Payroll
Upcoming regular payrolls can be retrieved using the GET companies/{company_uuid}/payrolls endpoint. The next upcoming payroll will be the earliest unprocessed payroll. You can use the optional query parameters to narrow down the response.
The example cURL below is filtering to show unprocessed payrolls, including off cycle, in the response there will be benefits and deductions, the dates for payroll is between 2021-02-01 and 2022-03-01. To see all query values review our API Reference.
curl --request GET \
--url 'https://api.gusto-demo.com/v1/companies/company_id/payrolls?processed=false&include_off_cycle=true&include=&include=deductions&start_date=2021-02-01&end_date=2021-03-31' \
--header 'accept: application/json' \
--header 'authorization: Bearer <<COMPANY_API_TOKEN>>'
const fetch = require('node-fetch');
const url = 'https://api.gusto-demo.com/v1/companies/company_id/payrolls?processed=false&include_off_cycle=true&include=&include=deductions&start_date=2021-02-01&end_date=2021-03-31';
const options = {
method: 'GET',
headers: {accept: 'application/json', authorization: 'Bearer <<COMPANY_API_TOKEN>>'}
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error('error:' + err));
This query will return an JSON array of payroll objects:
[
{
"version": "19289df18e6e20f797de4a585ea5a91535c7ddf7",
"payroll_deadline": "2021-02-18",
"check_date": "2021-02-22",
"processed": true,
"processed_date": "2021-02-18",
"payroll_id": 7786400908986532,
"payroll_uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",
"company_id": 7756341740978008,
"company_uuid": "6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb",
"pay_period": {
"start_date": "2021-02-01",
"end_date": "2021-02-15",
"pay_schedule_id": 7757500908984137,
"pay_schedule_uuid": "00ebc4a4-ec88-4435-8f45-c505bb63e501"
},
"totals": {
"company_debit": "121747.71",
"net_pay_debit": "79283.80",
"tax_debit": "42463.91",
"reimbursement_debit": "0.00",
"child_support_debit": "0.00",
"reimbursements": "0.00",
"net_pay": "81752.94",
"gross_pay": "130635.89",
"employee_bonuses": "0.00",
"employee_commissions": "18536.37",
"employee_cash_tips": "0.00",
"employee_paycheck_tips": "0.00",
"additional_earnings": "0.00",
"owners_draw": "0.00",
"check_amount": "2469.14",
"employer_taxes": "6917.19",
"employee_taxes": "35546.72",
"benefits": "0.00",
"employee_benefits_deductions": "13336.23",
"deferred_payroll_taxes": "0.00"
},
"employee_compensations": [
{
"employee_id": 1123581321345589,
"employee_uuid": "187412e1-3dbe-491a-bb2f-2f40323a7067",
"excluded": false,
"gross_pay": "2791.25",
"net_pay": "1953.31",
"payment_method": "Direct Deposit",
"fixed_compensations": [
{
"name": "Bonus",
"amount": "100.00",
"job_id": 1,
"job_uuid": "94e0d15e-9ed2-4077-98f6-64554f242ba5"
},
{
"name": "Reimbursement",
"amount": "100.00",
"job_id": 1,
"job_uuid": "91bc3b43-ded0-4ee7-98fe-215499e909ba"
}
],
"hourly_compensations": [
{
"name": "Regular Hours",
"hours": "40.000",
"job_id": 1,
"job_uuid": "bd378298-3e0c-4145-904a-baadf8a91fa3",
"compensation_multiplier": 1
},
{
"name": "Overtime",
"hours": "15.000",
"job_id": 1,
"job_uuid": "9d3760f0-d1f9-4700-8817-0fe2dce5cf23",
"compensation_multiplier": 1.5
},
{
"name": "Double overtime",
"hours": "0.000",
"job_id": 1,
"job_uuid": "b5eef9a9-4a87-4649-a80d-14878c05f44e",
"compensation_multiplier": 2
},
{
"name": "Regular Hours",
"hours": "40.000",
"job_id": 2,
"job_uuid": "332bd171-9efc-432b-abbb-a75c9dba706a",
"compensation_multiplier": 1
},
{
"name": "Overtime",
"hours": "5.000",
"job_id": 2,
"job_uuid": "ca9b3dc1-57ac-4736-901a-9b1c9634b9d5",
"compensation_multiplier": 1.5
},
{
"name": "Double overtime",
"hours": "0.000",
"job_id": 2,
"job_uuid": "1bad01e2-140c-49ed-9542-2388ce4a19b3",
"compensation_multiplier": 2
}
],
"paid_time_off": [
{
"name": "Vacation Hours",
"hours": "20.000"
},
{
"name": "Sick Hours",
"hours": "0.000"
},
{
"name": "Holiday Hours",
"hours": "0.000"
}
],
"benefits": [
{
"name": "Group Term Life",
"employee_deduction": "100.00",
"company_contribution": "50.00",
"imputed": true
},
{
"name": "401K",
"employee_deduction": "100.00",
"company_contribution": "50.00",
"imputed": false
}
],
"deductions": [
{
"name": "Child Support",
"amount": "80.00"
}
]
}
]
}
]
2. Update Payroll (Optional)
If there is information that is incorrect or that you would like to update for a given payroll you can use the PUT companies/{company_uuid}/payrolls/{pay_period_start_date}/{pay_period_end_date} endpoint. You will need to use the version to update a payroll.
You can update Regular Hours, Overtime, and Double overtime for Salaried Nonexempt employees, but only Regular Hours can be updated for Exempt employees since they are not eligible for overtime.
curl --request PUT \
--url https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/2021-02-01/2021-02-15 \
--header 'accept: application/json' \
--header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
--header 'content-type: application/json' \
--data '
{
"version": "19289df18e6e20f797de4a585ea5a91535c7ddf7",
"employee_compensations": [
{
"employee_id": 1123581321345589,
"employee_uuid": "187412e1-3dbe-491a-bb2f-2f40323a7067",
"excluded": false,
"payment_method": "Direct Deposit",
"fixed_compensations": [
{
"name": "Bonus",
"amount": "200.00",
"job_id": 1,
"job_uuid": "94e0d15e-9ed2-4077-98f6-64554f242ba5"
}
],
"hourly_compensations": [
{
"name": "Regular Hours",
"hours": "30.000",
"job_id": 1,
"job_uuid": "91bc3b43-ded0-4ee7-98fe-215499e909ba"
},
{
"name": "Double overtime",
"hours": "20.000",
"job_id": 1,
"job_uuid": "bd378298-3e0c-4145-904a-baadf8a91fa3"
},
{
"name": "Overtime",
"hours": "10.000",
"job_id": 2,
"job_uuid": "9d3760f0-d1f9-4700-8817-0fe2dce5cf23"
}
],
"paid_time_off": [
{
"name": "Vacation Hours",
"hours": "25.000"
},
{
"name": "Sick Hours",
"hours": "10.000"
},
{
"name": "Holiday Hours",
"hours": "8.000"
}
]
}
]
}
'
const fetch = require('node-fetch');
const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/2021-02-01/2021-02-15';
const options = {
method: 'PUT',
headers: {
accept: 'application/json',
'content-type': 'application/json',
authorization: 'Bearer <<COMPANY_API_TOKEN>>'
},
body: JSON.stringify({
version: '19289df18e6e20f797de4a585ea5a91535c7ddf7',
employee_compensations: [
{
employee_id: 1123581321345589,
employee_uuid: '187412e1-3dbe-491a-bb2f-2f40323a7067',
excluded: false,
payment_method: 'Direct Deposit',
fixed_compensations: [
{
name: 'Bonus',
amount: '200.00',
job_id: 1,
job_uuid: '94e0d15e-9ed2-4077-98f6-64554f242ba5'
}
],
hourly_compensations: [
{
name: 'Regular Hours',
hours: '30.000',
job_id: 1,
job_uuid: '91bc3b43-ded0-4ee7-98fe-215499e909ba'
},
{
name: 'Double overtime',
hours: '20.000',
job_id: 1,
job_uuid: 'bd378298-3e0c-4145-904a-baadf8a91fa3'
},
{
name: 'Overtime',
hours: '10.000',
job_id: 2,
job_uuid: '9d3760f0-d1f9-4700-8817-0fe2dce5cf23'
}
],
paid_time_off: [
{name: 'Vacation Hours', hours: '25.000'},
{name: 'Sick Hours', hours: '10.000'},
{name: 'Holiday Hours', hours: '8.000'}
]
}
]
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error('error:' + err));
3. Calculate the Payroll
Once a payroll is updated, use the PUT companies/{company_id}/payrolls/{payroll_id}/calculate endpoint to calculate the taxes, benefits, and deductions for the 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.
This calculation is asynchronous and a successful request responds with a 202 HTTP status. To view the details of the calculated payroll, use the GET /v1/companies/{company_uuid}/payrolls/{payroll_uuid} endpoint with show_calculation=true and include=taxes,benefits,deductions params.
Due to the complex nature of the calculations, we recommend using our Webhooks to await the
payroll.calculatedresponse before trying toGETthe calculations.
curl --request PUT \
--url https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/{payroll_uuid}/calculate \
--header 'authorization: Bearer <<COMPANY_API_TOKEN>>'
const fetch = require('node-fetch');
const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/{payroll_uuid}/calculate';
const options = {method: 'PUT', headers: {authorization: 'Bearer <<COMPANY_API_TOKEN>>'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error('error:' + err));
4. Submit Payroll
Preview UI
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 total payroll, taxes, and debits.
If everything looks accurate, a payroll can be processed using the PUT companies/{company_uuid}/payrolls/{payroll_uuid}/submit endpoint. 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.
This submission is asynchronous and a successful request responds with a 202 HTTP status. Upon success, the payroll status transitions to the processed state.
curl --request PUT \
--url https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/{payroll_uuid}/submit \
--header 'authorization: Bearer <<COMPANY_API_TOKEN>>'
const fetch = require('node-fetch');
const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/{payroll_uuid}/submit';
const options = {method: 'PUT', headers: {authorization: 'Bearer <<COMPANY_API_TOKEN>>'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error('error:' + err));
Cancel a Payroll
You can revert a payroll to the
unprocessedstate using thePUT /companies/{company_uuid}/payrolls/{payroll_uuid}/cancelendpoint. A payroll cannot be canceled after 3:30pm PST on thepayroll_deadline.
5. Receive Payroll Receipts and Paystubs
Once a payroll is submitted, we recommend including a summary of the payroll for the end user to view the debit date, check date, and payroll details. The payroll receipt should also be available on this final step. See Payroll Receipts for more information.
You can retrieve Payroll Receipt using the GET payrolls/{payroll_uuid}/receipt endpoint.
You can retrieve a W2 Employee's Paystub using the GET payrolls/{payroll_id}/employees/{employee_id}/pay_stub endpoint.
You can also use the pre-built UI Flow for a payroll receipt.
Updated about 1 month ago