POS Time Cards

Aggregate and indexed time card information from your POS system. Time cards track employee working hours for labor management and payroll.

Overview

The POS Time Card API provides access to employee time tracking data. Time cards record when employees clock in and out, including breaks and job changes during shifts.

Time Card Structure

Time cards have a hierarchical structure:

• TimeCard - Main record for an employee's work period
  • TimeCardSegment (1 or more) - Individual clock-in/clock-out segments

A single time card may contain multiple segments if an employee:

• Takes breaks
• Changes jobs during their shift
• Clocks in and out multiple times

API Endpoints

Retrieve Time Cards

Returns time card records for a specific location.

curl -X GET "https://conecto-api.shift4payments.com/pos/v2/12345/time-cards?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "results": [
    {
      "posRef": "TC-12345",
      "employeeRef": "EMP-001",
      "employeeName": "Jane Smith",
      "jobRef": "JOB-SERVER",
      "jobName": "Server",
      "status": "CLOSED",
      "clockInAt": "2024-01-15T10:00:00Z",
      "clockOutAt": "2024-01-15T18:00:00Z",
      "totalHours": 7.5,
      "regularHours": 7.5,
      "overtimeHours": 0,
      "breakMinutes": 30,
      "locationId": 12345,
      "timeCardSegments": [
        {
          "posRef": "TCS-001",
          "clockInAt": "2024-01-15T10:00:00Z",
          "clockOutAt": "2024-01-15T14:00:00Z",
          "jobRef": "JOB-SERVER",
          "jobName": "Server",
          "hours": 4.0
        },
        {
          "posRef": "TCS-002",
          "clockInAt": "2024-01-15T14:30:00Z",
          "clockOutAt": "2024-01-15T18:00:00Z",
          "jobRef": "JOB-SERVER",
          "jobName": "Server",
          "hours": 3.5
        }
      ]
    },
    {
      "posRef": "TC-12346",
      "employeeRef": "EMP-002",
      "employeeName": "John Doe",
      "jobRef": "JOB-COOK",
      "jobName": "Cook",
      "status": "OPEN",
      "clockInAt": "2024-01-15T11:00:00Z",
      "clockOutAt": null,
      "totalHours": null,
      "regularHours": null,
      "overtimeHours": null,
      "breakMinutes": 0,
      "locationId": 12345,
      "timeCardSegments": [
        {
          "posRef": "TCS-003",
          "clockInAt": "2024-01-15T11:00:00Z",
          "clockOutAt": null,
          "jobRef": "JOB-COOK",
          "jobName": "Cook",
          "hours": null
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 150
  }
}

Models

TimeCard

The main time card record representing an employee's work period.

TimeCardSegment

Individual clock-in/clock-out segments within a time card.

Use Cases

Labor Cost Analysis

Calculate and analyze labor costs:

• Total Labor Hours - Sum hours across all employees
• Labor Cost - Calculate total labor cost using wage rates
• Labor Percentage - Calculate labor as percentage of sales
• Overtime Tracking - Monitor overtime hours by employee

Payroll Processing

Export time card data for payroll:

• Regular vs. Overtime - Separate hours for different pay rates
• Tip Reporting - Include declared tips for payroll
• Department Breakdown - Track hours by department for cost allocation
• Break Time - Account for paid vs. unpaid breaks

Compliance & Reporting

Ensure labor law compliance:

• Hours Tracking - Monitor employee hours for overtime rules
• Break Compliance - Ensure required breaks are taken
• Minor Restrictions - Track hours for minor employees
• Audit Trail - Maintain records for labor law audits

Scheduling Optimization

Optimize labor scheduling:

• Actual vs. Scheduled - Compare scheduled to actual hours
• Labor Efficiency - Analyze labor efficiency by shift
• Peak Hours - Identify staffing needs by time of day
• Cross-Training - Track employees working multiple jobs

Best Practices