The Timesheets API is how you record and pay out the earnings that hourly W-2 employees earn on the clock. Hours on a worker's timesheet are recorded as "shifts", and we process shifts for payout on a regular payroll cycle.
We automatically handle the whole process of converting "raw" timeclock punches into accurate gross wages: overtime classification, multiple pay rates, multiple work locations, tax jurisdiction determination, automated corrections when errors occur, and more.
We support a variety of features and configurations in this API. They are documented below and in the API endpoints in this section.
⌚️ Work period & breaks
A “shift” refers to any part of a whole continuous work period. If an employee works a scheduled work period in two parts, like one part before a lunch break and another part after, these parts could be recorded as two shifts or the break could be recorded as a "break period" within the shift.
We automatically provide a default break type for unpaid breaks. The default segmentConfigCode value for this break type is "DEFAULT_UNPAID". We support both paid and unpaid breaks, and we can configure additional break types for paid or unpaid breaks upon request. You can have as many break types as you need.
🏋️♀️ Overtime classification
By default, we support the federal FLSA overtime rule and rules for the states that have additional overtime rules. We automatically apply overtime rules based on the work location where a shift was worked. You can set that work location using the overrideWorkLocationId field, or leave that field blank, so we'll use the default work location set on workers' profiles.
We support custom overtime classification rules, and the rules can be different for each state. Let us know at [email protected] if you need help configuring special overtime rules.
💵 Pay rate
You can set a shift-specific pay rate using the field effectiveHourlyPayRate. This is the regular rate at which the shift should be paid.
If a shift's regular rate is $20, you should pass 20.00 for its effectiveHourlyPayRate. We'll calculate regular hours at $20/hr, overtime hours at $30/hr, and double-time hours at $40/hr (unless any special overtime rules apply). These calculated rates are used to determine the gross wages for a shift.
If you don't set a shift-specific pay rate, we'll use the hourly pay rate on the worker's profile as a fallback.
You can optionally set a "display pay rate" for each shift as well. This is the rate that we'll display on the worker's pay stub, but is not used to calculate gross wages for a shift—it's for display only. This field is useful in cases where you need to adjust the effectiveHourlyPayRate based on business policy or regulations.
For example, if you need to calculate a weighted-average pay rate, you should set the calculated average rate using effectiveHourlyPayRate (i.e. $21.23) and set the quoted rate for the shift (i.e. $20.00) using displayHourlyPayRate. We'll calculate gross wages using $21.23/hr, but display $20.00/hr on the pay stub.
📍 Work location
When workers are staffed at different work locations per shift, it's critical to assign the correct work location for each shift to ensure the correct tax liability is determined for each location where work is performed. Providing a value for the parameter overrideWorkLocationId assigns a shift to a specific work location for tax purposes.
Work Locations API
Work locations must be created before you can assign them to shifts. There are no restrictions on how many work locations you can create. See the Work Locations API for more information about creating work locations.
If no value is provided, the work location assigned to the worker's profile is used by default.
When a work location is assigned to a shift, gross wages for that shift are subject to all employee– and employer–side taxes in effect for that location on the date of the shift. These taxes are automatically applied to the payment that pays out wages for this shift, typically in the next payroll batch.
If a payment pays out multiple shifts, each with assigned work locations, all appropriate taxes for each shift's work location will be applied to that payment.
✂️ Correcting timesheet errors
When a shift is missed or entered incorrectly in Everee, you can add, edit, or delete it until the date of the shift is paid-out, at which point the date is marked as "paid". At this point, you can no longer delete shifts on that date, but you can still correct a worker's timesheet by adding missing shifts or editing paid shifts that were entered wrong.
Adding or editing shifts on a paid-out date is called a timesheet correction.
Timesheet corrections are opt-in
Processing corrections via your API integration is easy, but corrections are historical adjustments to your workers' pay. As a result, corrections are only permitted when you opt into them by passing the query parameter
correction-authorized=trueto endpoints in the Timesheets API.This prevents any unintentional corrections from being created. Without passing that parameter, you could drive your day-to-day Timesheet integration without corrections and have a manual workflow to process corrections in the Everee portal as needed.
You can process corrections using the same Create a shift and Update a shift endpoints in the Timesheets API. We automatically determine the difference between what was paid-out for that date already (based on the existing timesheet) and what should have been paid (based on any new or changed shifts you provide).
The difference results in either an overpayment or underpayment scenario.
When an overpayment has occurred, we automatically record a payroll deduction on the worker's profile that will withhold the overpaid amount from their next payroll payment. This deduction is visible on the Job tab of the worker's profile in the Everee portal, under Benefits & Deductions.
When an underpayment has occurred, the worker needs to be paid the missing amount. You can tell us which of three approaches you want to use, based on the correctionPaymentTimeframe field in those API endpoints:
NEXT_PAYROLL_PAYMENT: we include the underpaid amount on the worker's next payroll payment.IMMEDIATELY: we create a one-time payment to pay out the underpaid amount ASAP, off-cycle from payroll.EXTERNALLY_PAID: we record that you have processed the underpaid amount via check or some other method. The amount will appear in the worker's gross wages, but it will not be paid-out via Everee.
Choosing an approach for underpayments
You should choose a "timeframe" approach for underpayments that aligns with your company policy and local regulation. We recommend choosing one approach and sticking to it whenever possible: this makes it easier to set expectations and communicate about resolving the timesheet error.
You can specify which approach you want to use by including the
correctionPaymentTimeframefield when you create or update a shift.This field is only meaningful when a correction is an underpayment, because there's money to be paid-out. If a correction is an overpayment, this field has no effect: you can still provide it, but it won't do anything since nothing will be paid-out.
The default setting is
NEXT_PAYROLL_PAYMENT. If you leave that field blank, we'll include the underpaid amount on the worker's next payroll payment.
Regardless of which underpayment approach you choose, the corrected hours will appear on the worker's pay stub marked as a "correction", so they can clearly see the difference between how they were originally paid and their corrected pay. That way, there's no confusion about what happened, even if the worker goes back to older pay stubs to review.