Labor API

Applies to: Labor API | Team API | Payments API

Learn about the Labor API and how to capture team member working hours with breaks, an hourly pay rate, and declared cash tips.

Link to section

Overview

The Labor API is the timekeeping component of the team management APIs provided by Square. Use the Labor API to integrate Square Point of Sale timekeeping with applications for labor cost reporting, payroll, and overtime management. The Labor API can also be used to integrate a time-clock application with a Square account for Square Dashboard labor reporting or Square Payroll. The API supports multiple paid or unpaid breaks per shift.

The Labor API is used with the Team API for team management tasks. For example, shifts created with the Labor API include team member and job details that are defined with the Team API.

Link to section

Requirements and limitations

Applications using OAuth require the following permissions:

  • Retrieving team members and team member wages: EMPLOYEES_READ.
  • Retrieving or managing workweek configurations and break types: TIMECARDS_SETTINGS_READ and TIMECARD_SETTINGS_WRITE.
  • Creating, updating, retrieving, and deleting shifts: TIMECARDS_WRITE and TIMECARDS_READ.

The Labor API uses information about team members and job assignments that is managed using the Team API. For example, the Team API can be used for the following operations:

  • Assign job-based wages to a team member.
  • Create new team members and manage their profiles.
Link to section

Manage team member time tracking

The Labor API can be used to record team member labor hours or import and export timekeeping data to applications. Shift records created by the API are visible in the Shifts application in the Square Dashboard. The Workday and Labor & tips pages show the work day hours completed and recorded by the API shift records as shown in the following figure:

Square dashboard, Workday app. One shift completed

Link to section

Track labor hours

Create a timekeeping application for Square account team members by providing the following:

  • Record the start time, end time, and breaks for a team member's work shift to compensate the team member for the actual time worked.
  • Set an hourly wage rate for a shift based on the job that a team member is doing on that shift.
  • Set break templates with a human-readable title, default duration, and payroll status to standardize team member shifts.
Link to section

Track tips

Recorded tips can be found in the following objects:

  • The tip_money field in a Payment object or the total_tip_money field in the Order object that corresponds to the payment.
  • The declared_cash_tip_money field in a Shift object.

To use the Payments API and Labor API to generate a tip report, the following must be true:

  • Tips are allocated directly to team members. Reporting on pooled tip allocations isn't supported.
  • Payments are processed by the team member who should be credited with the sale or tip. Square populates the team_member_id field with the ID of the team member who ran the payment.
  1. Call ListPayments to retrieve payments for a specific date range.

  2. Iterate over the payments and calculate the sales and tips for each team member:

    • amount_money - The sales amount. This amount might include taxes, fees, and discounts applied to the associated order but doesn't include tips.
    • tipping_money - The tip amount collected for the payment.
    • team_member_id - The team member who made the sale.
  3. Call SearchShifts to get shifts for the date range.

  4. Iterate over the shifts and find any declared cash tips:

    • declared_cash_tip_money - The cash tip amount declared for the shift.
    • team_member_id - The team member assigned to the shift.

Note

Learn about a sample application that calculates pooled tips for a shift.

Although processing fees apply to the total amount of each payment (including tip), Square Dashboard reports and Payment objects show the full tipped amount with no fees deducted.

Link to section

Import or export labor hours

Import and export team member labor hours for time-clock, labor and sales reporting, and overtime management solutions by providing the following:

  • Export Square account labor hours - Use the Labor API shift search endpoint to get labor hours data in a pay period for use in an existing payroll system.
  • Import timekeeping data - Track team member labor hours in an existing time-clock application and import the data into a Square account as Shift records. Generate labor and sales reports in the Square Dashboard or pay team members using Square Payroll.

The Labor API is available for server-side development as a set of REST endpoints.

Note

A shift is a record of a team member's start time and end time for a work period on a specific day. A shift records the hourly pay rate for the work period and the duration of any breaks taken.

Link to section

See also