Labor API

How It Works

This topic provides an overview of the Labor API object model and call flows.

Key functions of the Labor API Permalink Get a link to this section

The Labor API enables the following key functions:

Other Labor API functions include:

  • Define a workweek (see WorkweekConfig) for use in overtime calculations.

  • Create BreakTypes to define the name, duration, and paid status of a set of standard shift breaks.

To learn more about the features of the Labor API, see What It Does.

Labor API object model Permalink Get a link to this section

The Labor API provides these primary data types:

TypeDescription
ShiftA record of a team member's work period in a given day, which includes breaks and the hourly pay rate.
ShiftWageHolds the team member's job title and hourly rate for this shift. ShiftWage is embedded in the Shift record. The ShiftWage holds a snapshot of the team member's hourly rate at the time a shift is completed.
WageSettingDefines the straight or computed hourly rate that a team member is paid for doing a specific job. Changes in the hourly rate that a team member earns for a job are captured in WageSetting and used to populate ShiftWage objects in future shifts.
BreakHolds the start and end times for a break taken during a shift.
BreakTypeDefines the titles, expected durations, and paid status of breaks allowed at a location.

The Labor API object model captures the shift start and end, breaks taken, and shift wage. Standardized Breaks are created from break types and team member wages to get a job-based hourly rate for the kind of work a team member is doing on the shift.

The Labor API defines the relationship between Shift, ShiftWage, Break, and TeamMember resources.

diagram-shifts-api

Team members Permalink Get a link to this section

The Labor API works with the Team API by assigning a TeamMember to a Shift. To use the Labor API, complete the following team member related tasks in the Square Seller Dashboard:

  • Add location-specific salaried, hourly, or volunteer team members to a Square account.

  • Set timezone information for each business location. A business Location timezone field can also be set using the Locations API.

  • Optionally, set hourly or annual wages for team members based on their job titles. If wages are not assigned to a team member, shifts can still be recorded but wage hourly rates must be obtained from another source and then recorded in a Shift.

Labor API process flows Permalink Get a link to this section

A client application, such as a virtual timeclock in a restaurant POS application, completes process flows to start a shift, record breaks, and end a shift at the restaurant.

Note

The following process flows refer to open shifts. An open shift is a shift that a team member started but did not end. This can happen when a team member does not clock out at the end of the previous shift, leaving it open.

Step 1: Start a shift Permalink Get a link to this section

A bartender uses the POS in the restaurant bar to start a shift:

  1. The timeclock gets a list of team members by location and allows selection from the list.

  2. The timeclock queries for an open shift for the selected team member. If an open shift is found, it must be closed before a new open shift can be created.

  3. The timeclock gets a list of WageSetting objects for the selected team member and chooses a wage rate for a shift based on the selected WageSetting. For example, a team member is working as a bartender today and is paid the hourly rate for a bartender for the shift. Tomorrow, the team member might work as a cashier with a different hourly rate.

  4. The timeclock sends a request to create a new shift associated with a business location, team member, hourly wage, and date/time stamp when the team member starts the shift.

Note

Field values set in the ShiftWage should come from a WageSetting record. Optionally, the values can be set using values from another source such as a personnel datastore from another application.

The new shift is used to record any breaks that are taken during the work shift and record the end time of the shift.

Step 2: Record a break on a shift Permalink Get a link to this section

After starting a shift, the bartender takes a dinner break and uses the POS device at the front cashier station to record the dinner break and order a meal:

  1. The timeclock gets a list of team members by location and lets the bartender choose their name.

  2. The timeclock gets the open shift created in the previous process flow (Step 1: Start a shift).

  3. The timeclock reads the state of any breaks that might have been recorded during the shift.

    • If there is an open break, it is closed by setting the Break.end_at field.

    • If there are no open breaks, a new break is created.

  4. The timeclock creates and sends an update request with the updated shift to replace the current shift.

At the end of the break, the bartender ends the break from the bar POS device.

Step 3: End a shift Permalink Get a link to this section

The bartender uses the bar POS device to end the shift.

  1. The timeclock gets a list of team members by location and lets the bartender choose their name.

  2. The timeclock gets the shift created in the previous process flow (Step 1: Start a shift) by querying for the open shift for the selected team member.

  3. The timeclock reads the state of any breaks that might have been recorded during the shift and closes any open breaks.

  4. The timeclock sets the Shift.end_at field to close the shift.

  5. The timeclock creates and sends an update request with the updated shift to replace the current shift.

Shift reporting endpoints Permalink Get a link to this section

The Labor API includes several reporting endpoints including:

  • SearchShifts. This endpoint is used to export historic shift data such as a week's worth of shifts from a Square account to a reporting or payroll application. The endpoint allows flexible filtering and sorting with the use of a ShiftQuery object provided in the body of the POST.

  • ListTeamMemberWages. This endpoint returns all the wage levels assigned to a given team member.

  • ListBreakTypes. This endpoint returns all the break templates for a given location or all of a seller's locations.

Square API timecard management concepts Permalink Get a link to this section

The Labor API introduces new timecard management concepts and implements the deprecated Connect v1 API timekeeping concepts using new resource types:

Team member. A person who works for a seller as an employee, contractor, or volunteer and whose work hours must be tracked for payroll applications.

Timecard. The deprecated Connect v1 resource name for a record of the start and end times for a single shift. In the wider industry, Timecard is often a synonym for Timesheet, which often refers to a set of timeclock data that covers a whole workweek or pay period.

Shift. The new canonical title for Timecard.

Break. Either paid or unpaid time that a person is not expected to be doing work during a shift.

Workweek. A payroll and accounting-specific definition of the start of a week. It can be arbitrarily defined by the business owner. For many businesses (that are closed on weekends), Sunday night at midnight is the default. Businesses such as late night bars and clubs are open during these hours. They might shift the day or the time that a workweek starts (such as, to Tuesday night at 4 AM). Overtime rules and pay periods follow the cadence of these defined workweeks.

Workday. 24-hour increments starting on the first minute of a new workweek. If the workweek starts at 4 AM, then every workday starts and ends at 4 AM.

Labor API optimistic concurrency Permalink Get a link to this section

The Labor API uses Optimistic Concurrency to ensure that write operations on Labor API resources are reliable when multiple endpoints might write the same Labor API resources at the same time.

Related topics Permalink Get a link to this section