Skip to main content

​
🔹 Overview

This guide explains how to run time tracking from start to finish. You will use this flow to:
  • set up time tracking rules
  • assign those rules to employees
  • record clock-ins, breaks, and clock-outs
  • review and approve time cards
  • sync approved time to payroll

​
🔹 1. Set Up a Time Tracking Policy

Start by creating your company time tracking policy with addTimeTrackingPolicy. Think of this as your starting point for overtime rules. This policy defines:
  • dailyOvertimeThreshold
  • weeklyOvertimeThreshold
⚠️ Note: Before retiring a policy, unassign it from active employees first.

​
🔹 2. Assign Policy to Employees

Once your policy is in place, assign it to the right employees using addTimeTrackingPolicyAssignments. If an employee should no longer be tracked under that policy, remove the assignment with removeTimeTrackingPolicyAssignments. Use this when:
  • onboarding a new employee
  • moving an employee to a different role or location
  • removing time tracking access when it no longer applies

​
🔹 3. Employee Clock and Break Flow

Every shift should begin with clockIn. Employees then use these endpoints during the workday:
  1. Clock in at shift start.
  2. Start break when break begins.
  3. End break when break ends.
  4. Clock out at shift end.
⚠️ Warnings:
  • Out-of-order actions fail (for example, calling clockOut before clockIn).
  • Shift boundary rule: Shifts should stay within the same day. If an employee clocks in and does not clock out before midnight, this is treated as a missed punch.
To assess whether an employee is currently eligible to clock in or clock out, use getEmployeeTimeTrackingStatus. 📝 Note: clockOut can also be used when the employee is on an active break.

​
🔹 4. Admin Time Entry Adjustments

Use upsertTimeEntry to add or fix time entries. Use deleteTimeEntry to remove incorrect entries. Common use cases:
  • missed punches
  • bad import rows
  • corrections before approval

​
🔹 5. Time Card Approval Workflow

Approve/unapprove cards with updateTimeCardApprovals. Before approving:
  • review all entries for the pay period
  • confirm breaks and totals are correct
  • fix issues first, then approve
📝 Note: Time cards can be unapproved from both Approved and Synced status. This will allow edits to be made so the timecard can again be approved and synced.

​
🔹 6. Sync Approved Time to Payroll

Use syncTimeCardsToPayroll to move approved time cards into payroll inputs. This step:
  • sends approved hours into payroll calculations
  • ties hours to the selected pay period
⚠️ Note: Run sync only after approvals are complete for the target pay period. Only approved timecards will be synced to payroll.

​
📝 End-to-End Sequence

  1. Create policy (addTimeTrackingPolicy)
  2. Assign policy (addTimeTrackingPolicyAssignments)
  3. Employee records time (clockIn, startBreak, endBreak, clockOut)
  4. Admin fixes issues (upsertTimeEntry, deleteTimeEntry)
  5. Admin approves cards (updateTimeCardApprovals)
  6. Sync approved cards (syncTimeCardsToPayroll)