Structuring Earnings

Earnings types and custom Earning Codes

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.


Did this page help you?