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.
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.
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_READandTIMECARD_SETTINGS_WRITE. - Creating, updating, retrieving, and deleting shifts:
TIMECARDS_WRITEandTIMECARDS_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.
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:
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.
Recorded tips can be found in the following objects:
- The
tip_moneyfield in a Payment object or thetotal_tip_moneyfield in the Order object that corresponds to the payment. - The
declared_cash_tip_moneyfield 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_idfield with the ID of the team member who ran the payment.
Call ListPayments to retrieve payments for a specific date range.
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.
Call SearchShifts to get shifts for the date range.
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.
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
Shiftrecords. 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.