Applies to: Labor API | Team API | Locations API | Webhooks | GraphQL
Learn how to use the Labor API to capture team member work hours with breaks, pay rate, and declared cash tips.
The Labor API provides time-tracking features for team members. You can import and export timekeeping data between Square Point of Sale and third-party applications for labor cost reporting, payroll, and overtime management. You can also integrate a time clock application for Square Dashboard labor reporting or Square Payroll. The API supports:
- Recording labor hours with multiple paid or unpaid breaks and declared cash tips.
- Accessing team member wage information such as job title and hourly pay rate.
- Defining break types to standardize the name, expected duration, and paid or unpaid status of breaks.
- Configuring workweek settings for overtime calculations.
Timecards created by the API are visible in the Staff section of the Square Dashboard.
Note
The Labor API defines two types of shifts; be careful not to confuse them:
- A
ScheduledShiftis used to manage team schedules. - A
Shiftis used for payroll time tracking.Shiftis deprecated and replaced byTimecard.
The following requirements and limitations apply when managing timecards using the Labor API:
- Square API version 2025-05-21 or later is required to access or manage
Timecardobjects. In this version,Shift-related endpoints, data types, and webhook events are deprecated and replaced byTimecardequivalents. For more information, see Migration notes. - The
Timecard.wagefield contains wage information for the timecard (shift), such as the job title and hourly pay rate. To provide this information based on team member job assignments, the team member's wage settings must be configured using the Square Dashboard or Team API. For more information, see Set up new team members. Otherwise, wage settings must be obtained from another source and then recorded on the timecard for future reporting.
See additional requirements and limitations for timecard management.
A timecard records the hours worked by a team member for a single shift on a specific day.
The time-tracking workflow starts by creating a timecard with the start time, team member assignment, and location of the work shift. You can also provide team member wage information to integrate timecard data with payroll and labor cost reporting.
Update the timecard as needed to record the start and end times of any breaks (based on predefined break types). When the shift is completed, update the timecard to record any declared cash tips and set the end time. For detailed steps about this process, including code examples, see Start and End Timecards and Add Breaks to Timecards.
| Process | Steps |
|---|---|
| Start a timecard |
|
| Add breaks |
|
| End the timecard |
|
The following key concepts apply to time tracking with the Labor API:
A timecard is a record of the hours worked by a team member for a single shift on a specific day, including breaks and declared cash tips. Team members are people who work as an employee, contractor, or volunteer for a seller and whose work hours are tracked. Breaks are paid or unpaid time that the team member isn't expected to be doing work during the shift.
A timecard also typically includes wage information, such as job title, hourly pay rate, and tip eligibility. Timecards can be used to compensate team members for the shifts they worked and for labor reporting. To record labor cost on a timecard, you must specify the wage.hourly_rate field. Otherwise, the timecard has no associated pay amount. The pay rate from the team member's primary job aren't used by default.
Note
The Shift object and related endpoints, data types, and webhook events are deprecated and replaced by Timecard equivalents. For more information, see Migration notes.
Applications can import and export team member labor hours for time-clock, labor, and sales reporting and for overtime management solutions:
- Export labor hours - Use the
SearchTimecardsendpoint or GraphQLtimecardsentry point to get labor hours data in a pay period for use in an external payroll system. Optionally, use webhook events to track timecard activities. - Import timekeeping data - Track team member labor hours in an existing time-clock application and import the data into a Square account as timecards. Generate labor and sales reports in the Square Dashboard or pay team members using Square Payroll.
Tips can come from different sources and are recorded in different objects:
- Tips collected directly from payment methods are recorded in the
tip_moneyfield of a Payment object or thetotal_tip_moneyfield of the Order object that corresponds to the payment. - Cash tips declared by team members are recorded in the
declared_cash_tip_moneyfield of a Timecard 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, provided that the team member is logged in to a cash drawer shift.
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 SearchTimecards to get timecards for the date range.
Iterate over the timecards 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 timecard.
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.
A workweek (WorkweekConfig) defines the starting day and time of the business week, which factors into payroll and overtime calculations and accounting reporting periods. While many businesses use Sunday at midnight as the start time, a business can optionally configure different start times to better match their operating hours. For example, businesses such as bars and clubs that are open during late night hours might shift the day or the time that the week starts (such as to Tuesday night at 4 AM). You can use the Labor API to manage workweek settings.
All workdays within the workweek are 24-hour periods that start at this configured time.
The following is an example workflow for a virtual time clock in a restaurant POS application.
A team member uses the POS device in the restaurant bar to clock in.
- The time clock gets a list of team members by location and lets the team member choose their name.
- The time clock searches for an open timecard for the team member. An open timecard indicates that the team member forgot to clock out from their previous shift and must be closed before a new timecard can be created.
- The time clock gets the TeamMemberWage objects for the team member to retrieve the appropriate wage information for the timecard. Team members might have multiple job assignments; for example, they might be working a bartender shift or server shift with different hourly rates.
- The time clock creates a new timecard associated with the start time, team member assignment, location, and wage information.
Note
A TeamMemberWage object provides the wage information used for Timecard.wage fields. Optionally, your application can obtain these settings from another source, such as a personnel datastore in an external application.
During the shift, the team member clocks out for a dinner break from the POS device at the front cashier station.
The time clock gets a list of team members by location and lets the team member choose their name.
The time clock gets the open timecard for the current shift.
The time clock reads the state of any
breaksthat might have been recorded during the shift.- If there's an open break, it's closed by setting the
Break.end_atfield. - If there are no open breaks, a new break is created.
- If there's an open break, it's closed by setting the
The time clock starts the break by sending an update request with the updated timecard details to replace the current details. At the end of the break, the bartender ends the break from the bar POS device.
The time clock ends the break by sending another update request with the updated timecard details to replace the current details.
The bartender uses the bar POS device to clock out of the shift.
- The time clock gets a list of team members by location and lets the bartender choose their name.
- The time clock gets the open timecard for the current shift.
- The time clock verifies that all recorded breaks are ended.
- The time clock updates the
Timecard.declared_cash_tip_moneyfield with any cash tips declared by the bartender. - The time clock sets the
Timecard.end_atfield to close the shift. - The time clock creates and sends an update request with the updated timecard to replace the current timecard.
The Labor API provides a set of endpoints used for tracking team member work hours. Applications using OAuth to authorize API requests require appropriate permissions to call these endpoints.
Use the following endpoints to record the start time and end time for a work shift, the duration of any breaks taken, information about the job and the hourly pay rate, and declared cash tips.
| Endpoint | Permission | Description |
|---|---|---|
| CreateTimecard | TIMECARDS_WRITE | Creates a timecard (shift) with details such as start time, location, team member assignment, and wage information. |
| SearchTimecards | TIMECARDS_READ | Retrieves a paginated list of timecards matching specified criteria such as team member, date range, or status. |
| DeleteTimecard | TIMECARDS_WRITE | Deletes a timecard. |
| RetrieveTimecard | TIMECARDS_READ | Retrieves a single timecard by ID. |
| UpdateTimecard | TIMECARDS_READ, TIMECARDS_WRITE | Updates a timecard with changes such as breaks, end time, or declared cash tips. |
Use the following endpoints to create and manage break types. A break type defines the name, expected duration, and paid or unpaid status of a break that can be added to a timecard.
| Endpoint | Permission | Description |
|---|---|---|
| ListBreakTypes | TIMECARDS_SETTINGS_READ | Retrieves a paginated list of all break types for an account. |
| CreateBreakType | TIMECARDS_SETTINGS_WRITE | Creates a new break type for an account. |
| DeleteBreakType | TIMECARDS_SETTINGS_WRITE | Deletes an existing break type. |
| GetBreakType | TIMECARDS_SETTINGS_READ | Retrieves a single break type by ID. |
| UpdateBreakType | TIMECARDS_SETTINGS_READ TIMECARDS_SETTINGS_WRITE | Updates an existing break type. |
Use the following endpoints to get the job title, hourly pay rate, and tip eligibility to provide for the wage field on a timecard.
| Endpoint | Permission | Description |
|---|---|---|
| ListTeamMemberWages | EMPLOYEES_READ | Retrieves a paginated list of job and wage settings for team members. |
| GetTeamMemberWage | EMPLOYEES_READ | Retrieves a specific job and wage setting by ID. |
The Labor API provides these endpoints for convenience. You can also use the Team API to retrieve team member wage information.
Use the following endpoints to manage workweek start times for use in overtime calculations.
| Endpoint | Permission | Description |
|---|---|---|
| ListWorkweekConfigs | TIMECARDS_SETTINGS_READ | Retrieves a list of workweek configurations for an account. |
| UpdateWorkweekConfig | TIMECARDS_SETTINGS_READ, TIMECARDS_SETTINGS_WRITE | Updates a workweek configuration. |
For detailed steps that show how to use many of these endpoints for timecard management, see Start and End Timecards, Add Breaks to Timecards, and Get Completed Timecards.
Note
You can use the timecards (or deprecated shifts) entry point in Square GraphQL queries to access timecard data through read-only operations. GraphQL queries can improve performance and reduce development time by letting you request exactly the data you need in fewer, more compact data transfers.
Time-tracking operations use the following primary objects.
| Object | Description |
|---|---|
| Timecard (or deprecated Shift) | A record of the hours worked by a team member for a single shift on a specific day, including breaks and declared cash tips. The Timecard.wage field is a TimecardWage object that contains wage information for the timecard. |
| TimecardWage (or deprecated ShiftWage) | The job title, job ID, hourly pay rate, and tip eligibility settings for the timecard. This object is embedded in the Timecard.wage field and represents a snapshot of the team member's hourly rate at the time of the shift. |
| TeamMemberWage | Wage information that defines how much a team member earns for a specific job (such as job title, hourly pay rate, and tip eligibility). This convenience object can be used to populate the wage field for a timecard. It captures the straight or computed hourly rate of a job assignment in the team member's wage settings. |
| Break | Records the start and end times for paid or unpaid breaks taken during a shift. These objects are embedded in the timecard's breaks field. |
| BreakType | Defines the title, expected duration, and paid or unpaid status of a break allowed at a location. This information can be used to standardize the breaks for a timecard. |
The following diagram shows the relationship between Timecard, TimecardWage, Break, BreakType, TeamMemberWage, and TeamMember resources.
