Structuring Earnings

Employees get paid in a variety of ways, and Check's flexible and simple API supports that. Check allows you to pay employees at any combination of workplaces and for any combination of earnings. In this guide, we’ll walk through two ways to create earnings for employees with the Check API.

Define Earnings types

Earnings are defined in Check’s API as a list of objects under a payroll item, and look like this at the most basic level:

{
  "id": "itm_6bPCIDaiSrHj0h50J1ta",
  "payroll": "pay_pmT5GAxJG232NgWfyppY",
  "employee": "emp_FMssH75VFfjomWcNCEvL",
  "earnings": [
    {
      "type": "hourly",
      "amount": "160.00",
      "hours": 16.0,
      "workplace": "wrk_PMB5H75VFfjiuWcNCE55"
    },
    {
      "type": "bonus",
      "amount": "96.00",
      "workplace": "wrk_yuT56YxJG232MnHfyQ5c"
    }
  ]
}

In this payroll item, an employee has earned $160.00 of hourly wages for 16 hours of work at one workplace, and a $96.00 bonus at another workplace. These earnings are taxed differently, and that is controlled by the type and workplace of each earning. You’ll also notice that the bonus earning does not have an hours amount associated with it; this is because bonus is a non-hourly earning type. You can find a complete list of earning types supported by Check's API here.

📘

Workplaces

Each payroll item earning also requires a workplace. This requirement allows for the flexibility to pay employees who earn at multiple locations in a single pay period, such as waiters who work at more than one location of a restaurant chain.

When structuring earnings, it is important to understand how they will show up on the Paystubs API. Paystubs are what employees look at to understand their pay and are subject to compliance regulations. Presenting each kind of earning separately not only helps employees understand their pay, and get taxed correctly on their earnings, but is also required by law in most states. In this example, the earnings portion of the employee’s paystub would look like this:

Hourly - Regular  	$10.00 rate 	16 hr   $160.00 current   $800.00 YTD
Bonus        	                             $96.00 current   $126.00 YTD

You’ll notice that the earnings are grouped by type on the paystub, and in addition to showing the earning amounts and hours in the current period we also show year to date (YTD) information for each earning type.

Using Check’s earning types directly will be sufficient for most basic payroll use cases. Small and medium-sized businesses will generally not need to specify any additional earning types beyond the ones that Check already supports.

However, in certain industries, and for businesses with more complex employee compensation structures, further granularity may be desired. For these cases, Check exposes the concept of an Earning Code.

Create custom Earning Codes

Let's imagine the example of a restaurant employee who takes on different shifts and responsibilities, with different rates of pay for each. Throughout the pay period, this employee works two different shifts, day and night, and two different roles, dishwasher and cashier. Each combination of these results in a different hourly rate and should be shown separately on the paystub.

Example paystub for this restaurant employee:

Dishwasher - Day  	$10.00 rate   16 hr   $160 current   $800 YTD
Dishwasher - Night	$12.00 rate    8 hr    $96 current   $126 YTD
Cashier - Day     	$14.00 rate   14 hr   $196 current  $1024 YTD
Cashier - Night   	$16.00 rate    2 hr    $32 current    $88 YTD

Achieving this requires sending Check at least four earning objects on the payroll item, which are separately identifiable as earnings for a particular job (e.g. “Dishwasher – Day”). This is achievable with Earning Codes.

Define Earning Codes

Earning Codes provide a way for customers to define additional kinds of earnings beyond the basic set supported through Check’s earning types. Earning Codes are also company specific, so that some companies can have a long list of custom earning codes, while others may not.
To support the case outlined above, we need to create four Earning Codes for this company using the Earning Codes API.

One might look like this:

{
   "id": "erc_hkdNgIBVUIKtMCPsRUzJ",
   "company": "com_omSihPyKgr68wxFQ0xTn",
   "name": "Dishwasher - Day",
   "type": "hourly"
}

An earning code ID can then be used within a payroll item earning instead of type, like so:

{
  "id": "itm_6bPCIDaiSrHj0h50J1ta",
  "payroll": "pay_pmT5GAxJG232NgWfyppY",
  "employee": "emp_FMssH75VFfjomWcNCEvL",
  "earnings": [
	{
  	    "earning_code": "erc_hkdNgIBVUIKtMCPsRUzJ",
  	    "amount": "160.00",
  	    "hours": 16.0,
  	    "workplace": "wrk_PMB5H75VFfjiuWcNCE55"
	},
	...
  ]
}

Similar to how earnings are grouped and aggregated together based on type, they are also grouped and aggregated together based on earning_code when type is not set. This allows us to achieve the paystub laid out above through the use of four separate earning codes (one for each job). Note that type and earning_code are mutually exclusive on an earning object.

🚧

Code strings

Observant readers will see that when interacting with the API, there is another field called code on the payroll item earning objects. This is a remnant of a deprecated method of creating custom earnings in Check’s API and you should expect it to be removed in a future API version.

Calculating Gross Pay with Earning Rates

Gross pay is the amount of money employees are paid before taxes and deductions are taken out of their paycheck. Check’s Earning Rate API allows you to define hourly and salary rates per employee, which can be used to calculate gross pay. Multiple Earning Rates can be created for employees to account for all the different types of work they do.

The Earning Rate object is associated with a single employee and contains the following fields:

{
  "id": "rte_aOSqW0QTKcE1iVU1C5",
  "amount": "11.25",
  "period": "hourly",
  "employee": "emp_aslkj192j3laksdj",
  "name": "Dishwasher Weekend Rate",
  "active": true,
  "metadata": {}
}

Earning Rates can also store the salary of an employee. When creating an Earning Rate, instead of passing in an hourly period, you should pass in an annually period to reflect that this wage is for an annual salary:

curl -XPOST https://sandbox.checkhq.com/earning_rates -d '{
  "amount": "72000",
  "period”: "annually",
  "employee": "emp_axzjqzC5oOZ51h3mqmXK",
  "name": "Manager Night Shift"
}'

Running Payroll with Earning Rates

When it comes time to run payroll for an employee, you can include their Earning Rate in the earning object, along with the number of hours worked, earning type, and associated workplace.

{
    "employee": "emp_123m009djaslj09j21",
    "earnings": [
        {
            "earning_rate": "rte_aOSqW0QTKcE1iVU1C5",
            "type": "hourly",
            "hours": 30,
            "workplace": "wrk_mMGLZHNyoZJ5Tu6fdsDx"
         }
    ]   
}

Upon payroll creation, Check performs the gross pay calculation on your behalf and returns the following:

{
    "employee": "emp_123m009djaslj09j21",
    "earnings": [
         {
             "earning_rate": "rte_Tu6fMGfdmLfdsD6f",
             "type": "hourly",
             "hours": 30,
             "amount": "337.50",
             "workplace": "wrk_mLZHNyoZJ5Tu6fdsDx"
         }
    ]
}

In this case, the gross pay for this employee is reflected in the amount as $337.50. From there, you are ready to preview and approve payroll for that employee.

It’s important to note that when passing in an Earning Rate for a salaried employee, gross pay is calculated by determining the salary’s hourly rate and multiplying it by the hours passed in the earning item. For salaried exempt full-time employees, it is standard to base this off of a 2,080-hour work year, or a 40-hour work week. This manifests itself in the following ways for different pay frequencies:

The only cases where you would adjust these hours for a salaried employee would be to accommodate an employee starting or leaving the company mid-week, or to adjust the salary at the end of the year to avoid overpaying the employee (for monthly and semi-monthly cases). Note: the Earning Rate API only supports calculation for salaried exempt employees and salaried non-exempt employees who are working at least 40 hours. If an employee who is salaried non-exempt works more than 40 hours, those extra hours should be accounted for in a separate earning item with the type overtime. Here is an example of using an Earning Rate for a salaried non-exempt employee with an additional Earning Rate for overtime:

{
    "employee": "emp_123m009djaslj09j21",
    "earnings": [
        {
            "earning_rate": "rte_aOSqW0QTKcE1iVU1C5",
            "type": "salaried",
            "hours": 40,
            "workplace": "wrk_mMGLZHNyoZJ5Tu6fdsDx",
        },
        {
            "earning_rate": "rte_9fqj90qjfqfjq4WEFJ",
            "type": "overtime",
            "hours": 5,
            "workplace": "wrk_mMGLZHNyoZJ5Tu6fdsDx",
        }
    ]
 }

When running payroll, either an amount or earning_rate should be set, but not both. If you have already done the gross pay calculation in your application, you should use amount and not earning_rate. The employee ID must also match the ID associated with the Earning Rate.

Earning Rates and Earning Codes

Earning Rates can be used in conjunction with Earning Codes within the earning object, as shown below:

{
    "employee": "emp_123m009djaslj09j21",
    "earnings": [
          {
              "earning_rate": "rte_aOSqW0QTKcE1iVU1C5",
               "earning_code": "erc_i288utwaa876672", 
               "hours": 30,
               "workplace": "wrk_mMGLZHNyoZJ5Tu6fdsDx"
           }
    ]
}