Labor API

How it Works

A deeper look at the Labor API

Languages Supported
Additional Resources

Key functions of The Labor API

The Labor API enables the following key functions:

Other Labor API functions include:

  • Define a work week (WorkweekConfig) for use in overtime calculations.
  • Create BreakTypes to define the name, duration, and paid status of a set of standard shift breaks.

Read What It Does to learn more about the features of the Labor API.

Labor API Object Model

The Labor API provides these primary data types:

  • Shift: A record of an employee's work period in a given day. Includes breaks and hourly pay rate
  • ShiftWage: Holds the employee's job title for the shift and their hourly rate for the shift. ShiftWage is a complex type embedded in the Shift record. If ShiftWage field values are taken from an EmployeeWage record, the ShiftWage holds a "snapshot" of the employees hourly rate at the time a shift is completed.
  • EmployeeWage: Defines the straight or computed hourly rate that an employee is paid for doing a specific job. Changes in the hourly rate that an employee earns for a job are captured in the EmployeeWage and used to populate ShiftWage objects in future shifts.
  • Break: Holds the start and end times for a break taken during a shift.
  • BreakType: Defines 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 employee wages to get a job-based hourly rate for the kind of work an employee is doing on the shift.

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

Diagram shifts api

Employees

The Labor API works with the Employees API to assign an Employee to a Shift. To use the Labor API, complete the following employee-related tasks in the Square Dashboard:

  • Add location-specific salaried, hourly, or volunteer employees to a Square account.
  • Set timezone information on each business location. A business Location timezone field can also be set programmatically using the Locations API.
  • Optionally, set hourly or annual wages for employees based on their job titles. If wages are not assigned to an employee, 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

A client application such as a virtual timeclock in a restaurant POS app 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 an employee started but did not end. This can happen when an employee did not clock out at the end of the previous shift, leaving it open.

1. Start a Shift

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

  1. The timeclock gets a list of employees by location and allows selection from the employee list.
  2. The timeclock queries for an open shift for the selected employee.
    1. 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 EmployeeWages for the selected employee and chooses a wage rate for a shift based on the selected EmployeeWage. For example: An employee is working as a "bartender" today and will be paid the hourly rate for a "bartender" for the shift. Tomorrow they may 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, employee, hourly wage, and date/time stamp when the employee starts the shift.

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

2. Record a break on a shift

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

  1. The timeclock gets a list of employees by location and lets the bartender click on their name.
  2. The timeclock gets the open shift created in the Start a Shift process flow.
  3. The timeclock reads the state of any breaks that may have been recorded in 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 their break from the bar POS device.

3. End a shift

The bartender uses the bar POS to end their shift.

  1. The timeclock gets a list of employees by location and lets the bartender click on their name.
  2. The timeclock gets the shift created in the Start a Shift process flow by querying for the open shift for the selected employee.
  3. The timeclock reads the state of any breaks that may have been recorded in the shift and then 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

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.
  • ListEmployeeWages: This endpoint returns all of the wage levels assigned to a given employee.
  • ListBreakTypes: This endpoint returns all of the break templates for a given location or all of a seller's locations.

Connect v2 timecard management concepts

The Connect v2 Labor API introduces new timecard management concepts and implements Connect v1 API timekeeping concepts using new resource types.

Timecard - The current 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 isn't expected to be doing work during their 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 those hours. They may shift either the day or the time a workweek starts (e.g., to Tuesday night at 4 AM). Overtime rules and pay-periods follow the cadence of these defined work-weeks.

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

Labor API Optimistic Concurrency

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

Prev
< What it Does
Next
Build with Labor API >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow