Skip to main content

Workforce Management

Introduction​

This guide outlines the standard workflow for integrating a Workforce Management (WFM) or Payroll system with Lightspeed Restaurant (K-Series). It covers authentication, retrieving sales data for labor cost calculations, tip attribution, and syncing staff and shift (clock-in/out) records.

Step 1 - Authentication and Mapping Business Locations​

Before pulling data, your application must authenticate and map the merchant's locations.

OAuth2 Authorization​

Use the V2 OAuth2 flow to generate access tokens.
Reference: Authentication Tutorial

Location Mapping​

Call the Financial API to retrieve the businessLocationId for the merchant's venues.
Reference: Get Businesses

Step 2 - Syncing Sales Data​

WFM systems typically require end-of-day or periodic sales syncs to calculate Labor Cost Percentages.

Fetch Sales​

Use the Financial API to pull aggregated or receipt-level sales data.
Reference: Get Business Location Sales

Transaction Types​

When processing financial data, ensure your system correctly handles all K-Series accounting transaction types to avoid discrepancies. Pay special attention to transitory types and how open accounts are carried over to the next day.

References:

Step 3 - Syncing Staff and Shifts​

To generate payroll and enforce scheduling, you must sync POS users and their clock times.

Staff API​

Pull the list of active employees and their assigned user groups.
Reference: Staff Endpoint

Shifts API​

Retrieve historical clock-in and clock-out times.
Reference: Get Shifts

Shift Webhooks​

For real-time clock-in/out updates, subscribe to shift webhooks rather than polling the API.
Reference: Create Webhook

Step 4 - Tip Management & Attribution​

Tip data is not stored in the Shift records. Instead, tip amounts and their corresponding staff attributions are extracted from the Financial API via receipt-level sales data.

Tip Amount​

Found within the payments array of each sale object.
Reference: payments.tip

Attributing Tips to Staff​

You can attribute the tip to an employee in two ways, depending on the merchant's tip-pooling rules:

  • By Payment Taker

    Use payments.staffId to attribute the tip to the employee who processed the payment.
    Reference: payments.staffId

  • By Receipt Owner

    Use ownerId or ownerName to attribute the tip to the server who owns the overall table/order, regardless of who took the payment.

    References:

Frequently Asked Questions (FAQ)​

Q: Is a job title or job code included in the Staff API?​

A: The user group is the closest match to a job title or code (e.g., Manager, Server, Busser).

Q: Do you support multiple job codes for a single staff member? (e.g., a user works 3 hours as a server, then 2 hours as a busser)​

A: Currently, K-Series uses a 1:1 mapping. A user can only belong to one user group at a time. If an employee has multiple roles, the merchant must create them as separate POS users and assign each user to their respective user group.

Q: Can we pull a general list of all jobs/roles used on the system to preconfigure tip rules?​

A: The closest match is pulling the list of user groups. Please note that tip rules are not pre-set at the user group level within K-Series.

Q: Do you support a dedicated Payroll ID field?​

A: The API provides a Staff ID. There is currently no dedicated Payroll ID field available.

Q: Are tip amounts included directly in each Shift record?​

A: No, aggregated tips are not included in the Shift endpoint. To retrieve tip data, query the Financial API using from/to parameters. The financial response returns the Staff ID on each sale/payment line, along with the corresponding tips as detailed in Step 4.

Q: How do we handle situations where the POS automatically clocks an employee out at the end of the day because they forgot?​

A: Merchants can configure a strict setting in the K-Series Back Office that requires users to settle open orders before they are allowed to clock out. This helps prevent unintentional shift closures and missing data.