Gross-up

Grossing up a paystub calculates a higher gross (pre-tax) pay amount so that after taxes are withheld, the employee's net pay equals a specific target amount instead of the usual case, where you set the gross amount and the net pay falls out of it. Use this when you want to guarantee an employee a specific take-home amount on a bonus, or on their whole paycheck, and want Worklio to calculate the gross amount required to get there.

This applies to a specific paystub within a payroll run, so it's a follow-up step after starting a payroll run and identifying the paystub you want to gross up.

Auth

Requires a bearer access token (see How to Get API Access).

Endpoint

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{RUN_ID}/paystubs/{PAYSTUB_ID}/grossup

CLIENT_ID is the company identifier returned as id when you create the company. RUN_ID is the runId returned when you start a payroll run. PAYSTUB_ID identifies the specific paystub within that run get it from the payroll run overview endpoint:

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{RUN_ID}/overview

Request fields

Field	Type	Required	Description
`mode`	integer (enum)	Yes	What's being grossed up. See Mode values below.
`payCode`	integer (enum)	Yes	Which earnings pay code this gross-up applies to. See Pay Code values below. Required and meaningful for both modes.
`amount`	number	Yes	The target net amount — what the employee should actually receive after taxes. Worklio calculates the gross amount required to net this.
`workLocationId`	integer	Yes	Which work location this gross-up amount is attributed to, for tax purposes (see `workLocationId` in Create a Work Location). `0` attributes it to the employee's home-based work rather than a specific company work location.

Mode values

Value	Name	Meaning
1	`Bonus`	Gross up a bonus amount.
2	`WholeCheck`	Gross up the whole paycheck.

Pay Code values

Value	Name	Meaning
0	`AdditionalEarnings`	Additional pay codes earnings.
1	`Bonus`	Bonus included in a regular payroll.
2	`Commission`	Commission paid on a regular payroll.
3	`Overtime`	Overtime paid at defined times the average hourly rate.
4	`OtherFlatAmount`	Other flat amount earnings.
5	`PaidTimeOff`	Time off pay for use with both hourly and salaried employees.
6	`Hourly`	Pay based on hours worked.
7	`SalaryWithHours`	Salary amounts recorded with hours worked.
8	`SickTime`	Sick time.
9	`Contractor1099`	Non-taxable amounts paid to non-employee contractors.
10	`Reimbursement`	Reimbursements for various types of expense.
13	`UnitsWithHours`	Pay based on units with hours worked recorded.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const RUN_ID = 1002115;
const PAYSTUB_ID = 10083; // from the payroll run overview endpoint
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/payroll/${RUN_ID}/paystubs/${PAYSTUB_ID}/grossup`;

const payload = {
  mode: 1, // Bonus
  payCode: 10, // Reimbursement
  amount: 1000,
  workLocationId: 0
};

async function grossUpPaystub() {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status);
  console.log(await response.text());
}

grossUpPaystub();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/payroll/1002115/paystubs/10083/grossup" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" \
  -d '{
    "mode": 1,
    "payCode": 10,
    "amount": 1000,
    "workLocationId": 0
  }' | jq .

Example response

{
  "paystubId": 10083,
  "mode": 1,
  "payCode": 10,
  "workLocationId": 0,
  "wcCode": "0000",
  "amount": 1000
}

wcCode is the workers' comp code applied to this gross-up entry.

Error response — gross-up already exists

{
  "status": 0,
  "code": "500",
  "errorCode": null,
  "message": "9/16/2026 - 11:13:10 AM : Paystub Gross Up already exists.",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

🚧
This returns an HTTP 500, not a 400 or 409 — that's the API's actual behavior, not a mistake in this guide. Treat the 500 plus this message as the signal that the paystub already has a gross-up, rather than as a generic server error.

A paystub can only have one gross-up at a time. To change the amount, mode, pay code, or work location on an existing gross-up, use PATCH on this same endpoint instead of POST. To remove one entirely, use DELETE on this same endpoint.

PATCH https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{RUN_ID}/paystubs/{PAYSTUB_ID}/grossup
DELETE https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{RUN_ID}/paystubs/{PAYSTUB_ID}/grossup

Notes

A second POST to the same paystub's gross-up endpoint fails with the 500 shown above. Use PATCH to update an existing gross-up, or DELETE to remove it and start over.
workLocationId: 0 attributes the gross-up to the employee's home-based work rather than a specific company work location, consistent with workLocationId elsewhere in the API.