Time Clock
The time clock records actual hours worked — distinct from shifts, which are the scheduled roster. A time entry is created when a staff member clocks in and closed when they clock out. Breaks can be tracked inside an entry, and worked time is always (clock out − clock in) − break minutes.
When a staff member clocks in, the entry is automatically linked to their scheduled shift for that day (in the supplier's timezone) when one exists. Unscheduled staff can still clock in — the entry simply stands alone.
The time entry object
| Field | Type | Description |
|---|---|---|
id | integer | Unique identifier |
staff_id | integer | The staff member |
staff | object | Staff summary (id, first_name, last_name) when loaded |
staff_shift_id | integer | null | Auto-matched scheduled shift, if any |
clock_in_at | string (ISO 8601) | Actual start of work (UTC) |
clock_out_at | string (ISO 8601) | null | Actual end of work — null means currently on the clock |
is_on_break | boolean | Whether a break is in progress |
break_started_at | string (ISO 8601) | null | When the in-progress break started |
break_minutes | integer | Accumulated break time (deducted from worked time) |
worked_minutes | integer | Derived worked time; open entries count up to now |
source | string | Where the punch came from: kiosk, app, or manager |
clocked_in_by / clocked_out_by / edited_by | integer | null | User IDs for manager punches and corrections |
notes | string | null | Free-text note (e.g. "forgot to clock out — corrected") |
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/staff/time-entries | List time entries |
| GET | /v1/staff/time-entries/{id} | Get a time entry |
| POST | /v1/staff/time-entries/clock-in | Clock a staff member in |
| POST | /v1/staff/time-entries/{id}/clock-out | Clock an entry out |
| POST | /v1/staff/time-entries/{id}/break/start | Start a break |
| POST | /v1/staff/time-entries/{id}/break/end | End a break |
| POST | /v1/staff/time-entries | Create a complete manual entry |
| PATCH | /v1/staff/time-entries/{id} | Adjust an entry |
| DELETE | /v1/staff/time-entries/{id} | Delete an entry |
| GET | /v1/staff/timesheet | Aggregated hours per staff member for a date range |
| POST | /v1/staff/timesheet/send-to-payroll | Send hours for the open pay period to Xero Payroll now |
Scopes
Reading uses staff:read; clocking and corrections use staff:write.