Time Cards

get

http://{{apiurl}}/api/v1/labor/timecards

Time Cards

The Time Cards endpoint returns individual employee timecard entries for a given payroll period or business date.

When calling this endpont, you must provide either a payrollPeriodId or an id.

Provide payrollPeriodId to obtain a list of Time Cards for the given payroll period.
- You may include an optional employeeId query parameter to filter the result to only that employeeId
Provide id to obtain a specific Time Card

Each record represents a single work session (clock-in and clock-out) and includes payroll, overtime, and performance metrics such as labor hours, pay calculation details, and sales contribution.

Description

Retrieves a list of timecard records for the active venue or license.

Each record reflects a single shift and contains metadata on time worked, pay, overtime, and associated sales metrics.

Response Structure

Field	Type	Description
`records`	array	Array of timecard objects.
`length`	integer	Number of records returned.
`status`	string	Request result (`"SUCCESS"` if successful).
`count`	integer	Total records matching the request.
`duration`	number	Time (in seconds) the API took to process the request.
`serverRequestTimestamp`	string (ISO 8601)	When the request reached the NX server.
`serverResponseTimestamp`	string (ISO 8601)	When the response was sent.
`serverClientDrift`	number	Time offset between client and server.

TimeCard Object

Field	Type	Description
`id`	string	Unique identifier for the timecard record.
`updatedAt`	string (ISO 8601)	Timestamp when the record was last updated.
`name`	string	Employee’s display name in “Last, First” format.
`dateTimeStart`	string (ISO 8601)	Clock-in timestamp for the shift.
`firstName`	string	Employee’s first name.
`lastName`	string	Employee’s last name.
`payrollPeriodId`	string	Identifier linking this record to a specific payroll period.
`parentId`	string	The corresponding employee ID.
`meta`	object	Detailed time, pay, and sales metrics for this timecard.

`meta` Object

The meta object contains structured sub-objects representing the breakdown of time, pay, and associated sales metrics.

`meta.display`

Formatted strings for time totals, as displayed in the NX system.

Field	Type	Description
`breakTimeDisplay`	string	Total break duration (formatted `HH:MM`).
`overtimeDisplay`	string	Overtime duration.
`totalTimeDisplay`	string	Total worked time for this shift.
`payableHoursDisplay`	string	Payable hours after adjustments.
`regularTimeDisplay`	string	Regular worked hours.

`meta.durations`

Raw duration metrics in minutes, used for calculations and compliance reporting.

Field	Type	Description
`totalMinutes`	number	Total minutes worked in the shift.
`breakTotalMinutes`	number	Minutes taken as unpaid breaks.
`regularTimeMinutes`	number	Minutes of regular paid time.
`overtimeTotalMinutes`	number	Minutes of total overtime.
`dailyOvertimeMinutes`	number	Minutes of daily overtime.
`weeklyOvertimeMinutes`	number	Minutes of weekly overtime.
`dailyDoubleOvertimeMinutes`	number	Minutes of daily double-time overtime.
`sixthDayOvertimeMinutes`	number	Minutes worked as sixth consecutive day overtime.
`seventhDayOvertimeMinutes`	number	Minutes worked as seventh consecutive day overtime.
`regularRemainingMinutes`	number	Minutes remaining before reaching daily overtime threshold.
`cumulativeWeeklyMinutes`	number	Accumulated weekly minutes worked.

`meta.jobId` / `meta.jobName`

Identifies the role or job position associated with this shift.

Field	Type	Description
`jobId`	string	Job configuration identifier.
`jobName`	string	Name of the job or role (e.g., “GM”, “Server”).

`meta.pay`

Breakdown of pay rates and totals for this timecard, including regular, overtime, and gratuity pay.

All totals are expressed in minor currency units (e.g., cents).

Field	Type	Description
`basePayRateTotal`	number	Regular base pay earned.
`regularPayTotal`	number	Total regular pay (excluding overtime).
`dailyOvertimePayTotal`	number	Pay earned from daily overtime hours.
`dailyDoubleOvertimePayTotal`	number	Pay from double-time daily overtime.
`weeklyOvertimePayTotal`	number	Pay earned from weekly overtime.
`sixthDayOvertimePayTotal`	number	Pay from sixth-day overtime.
`seventhDayOvertimePayTotal`	number	Pay from seventh-day overtime.
`gratuityTotal`	number	Total gratuities earned.
`payTotal`	number	Combined total pay for the shift.

`payPerHour[]`

Detailed pay and activity per hour block within the shift.

Field	Type	Description
`hour`	string	Hour of the day in 24-hour format.
`payIncurred`	number	Total pay accrued during this hour (minor units).
`minutesWorked`	number	Number of minutes worked during this hour.

`meta.timeCardSales`

Sales performance metrics recorded during the employee’s active timecard window.

Field	Type	Description
`salesTotal`	number	Total sales attributed to this timecard.
`tippableSalesTotal`	number	Portion of sales eligible for tipping.
`cashPaymentsTotal`	number	Total cash payments processed.
`creditPaymentsTotal`	number	Total credit card payments processed.
`nonCashPaymentsTotal`	number	Other non-cash payment totals.
`gratuitiesTotal`	number	Combined gratuities recorded.
`cashTipsTotal`	number	Cash tips received.
`creditCardTipsTotal`	number	Credit card tips received.
`tipsTotal`	number	Aggregate tips (cash + credit).
`tipsDeclared`	number	Tips declared by the employee.
`tipsRetainedTotal`	number	Portion of tips retained by the employee.
`tipsDisbursed`	number	Tips distributed to the employee.
`discountsTotal`	number	Discounts applied to sales under this employee.
`checkCount`	number	Number of checks handled during this shift.
`guestCount`	number	Total number of guests served.
`averageCheck`	number	Average check amount.
`averageGuest`	number	Average per-guest spend.
`checkOpenAverageMinutes`	number	Average time a check remained open.
`accountableCheckIds`	array	IDs of checks linked to this timecard.
`tipDistributions`	array	Records of tips distributed (if applicable).

Example Response

{
  "records": [
    {
      "id": "84a9496e-15d7-4d1a-b5ad-c73f8d95befc",
      "updatedAt": "2025-11-02T19:01:40.390Z",
      "name": "Wermes, Brandon",
      "dateTimeStart": "2025-11-02T14:32:02.365925Z",
      "firstName": "Brandon",
      "lastName": "Wermes",
      "payrollPeriodId": "5be7bc7a-b830-49a9-a84d-0b80ad45fa7c",
      "parentId": "d28f737f-c507-44b8-8f39-f9e09f55c256",
      "meta": {
        "display": {
          "breakTimeDisplay": "00:00",
          "overtimeDisplay": "00:00",
          "totalTimeDisplay": "04:32",
          "payableHoursDisplay": "04:32",
          "regularTimeDisplay": "04:32"
        },
        "durations": {
          "totalMinutes": 272,
          "regularTimeMinutes": 272,
          "overtimeTotalMinutes": 0
        },
        "jobId": "fd782280-f1fb-4e40-9727-8eb76b66be75",
        "jobName": "GM",
        "pay": {
          "regularPayTotal": 0,
          "payTotal": 0,
          "payPerHour": [
            { "hour": "06", "payIncurred": 0, "minutesWorked": 27 },
            { "hour": "07", "payIncurred": 0, "minutesWorked": 60 }
          ]
        },
        "timeCardSales": {
          "salesTotal": 0,
          "tippableSalesTotal": 0,
          "tipsTotal": 0,
          "checkCount": 0
        }
      }
    }
  ]
}

Notes

All monetary values (pay and sales) are expressed in minor units (e.g., cents).
The meta object provides both formatted display values and raw calculation data.
If an employee works multiple shifts in a day, each shift is represented as a separate timecard record.
payrollPeriodId links the timecard to its governing payroll period for accurate overtime and reporting calculations.