Migrate from the Connect V1 Timecards API

The following information helps you migrate your Connect V1 Timecards API code to the new Square Labor API. For general guidance about the differences between Connect V1 and Square APIs, see the Connect V1 Migration guide.

Link to section

Migration overview

The Connect V1 Timecards API lets you capture employee work hours. The Square Labor API captures work hours including breaks and allows for multiple wage levels per employee by job title.

Link to section

Important dates

  • Deprecation: 2020-02-26
  • Retirement: 2021-02-26
Link to section

If you need help

If you need help migrating to Square APIs or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager.

Link to section

General differences between the Timecards API and Labor API

  • Flexible multi-object Shift model. The Square Labor API captures each employee shift as a parent Shift object with nested Break objects to capture multiple shift breaks and a ShiftWage object to capture the hourly rate and job title of the employee on a given shift.
  • Timezone recording. The timezone where an employee works a shift is recorded. This ensures that regular, overtime, and doubletime calculation is correct across the timezones in which an organization operates.
  • Labor Template objects. The Square Labor API provides EmployeeWage objects for setting an employee's wage for a job title on future shifts for that job title, a BreakType template object to define standard break durations, and WorkweekConfig objects used to calculate overtime pay.
  • V2 Webhooks support. Webhook notifications are generated for all subscribing endpoints on all create, update, and delete operations on a Shift object. Use webhooks to integrate with another system without polling for state changes.
Link to section

Get V1 timecards information using the Labor API

You can use the Labor API to retrieve V1 timecards information for reporting. Any timecards created with v1Employees.Timecards to record breaks are represented as unique Shift objects in the Labor API. Labor functionality, such as shift wages and breaks, are not available on V1 timecards retrieved with the Labor API.

Link to section

Discontinued functionality

  • The Square Labor API does not allow for starting and ending a shift in different locations.
  • The non-working V1 Timecard overtime calculation feature is discontinued. The Square Labor API does not calculate regular, overtime, and double time seconds worked on a shift. To learn about calculating labor costs, see Timecards FAQ.
  • The audit functionality of the v1TimeCardEvent object is not available in the Square Labor API. To replicate this functionality, use V2 Webhook notifications for the Labor API to update a log in your system. The v1TimeCardEvent.event_type indicates the source of the update as API, Square Register, or Seller Dashboard. The source of a Shift update is not available.
Link to section

Webhook and endpoint mapping

Link to section

Webhooks

labor.shift.created, labor.shift.updated, and labor.shift.deleted notify a listener when the Square Register, Seller Dashboard, or Labor API change the state of a Shift. For more information, see Labor Webhooks.

Link to section

Endpoints

Square Labor API endpoints replace the Timecards endpoints in the V1 Employees API. The Labor API supports individual calls for creating, retrieving, updating, and deleting labor entities such as shifts, employee wage settings, and break types. Workweek configurations can only be retrieved by the Labor API.

You must update the code that relies on the following endpoints to avoid breaking when the V1 Employees.Timecards API retires:

V1 Timecards endpointReplacementUsage
CreateTimecardCreateShiftUsed to create a new employee shift.
DeleteTimecardDeleteShiftUsed to delete a shift.
ListTimecardsSearchShiftsUsed to retrieve a filtered and sorted set of shifts.
ListTimecardEventsNo direct replacementUse SearchShifts to get a set of Shift objects in their current state. Subscribe to V2 Webhooks Labor events to capture and record state changes on Shift objects.
RetrieveTimecardGetShiftUsed to retrieve a single shift by Shift.id.
UpdateTimecardUpdateShiftUsed to update a shift (such as to record a break, clock out, or change a shift wage).
Link to section

Migration examples

The following examples compare common time keeping REST operations for the Employees.Timecards and Labor APIs.

Link to section

Clock in

With the V1 Timecards API, you create one TimeCard record for an employee shift. Record the employee ID and clock-in time.

When you migrate your code to use the Labor API, you open a new shift and record the employee ID, clock-in time, and the wage rate to be earned on the shift based on the employee job title for the shift.

Link to section

Labor API: Create a shift

Link to section

Employees.Timecards: Create a timecard

curl https://connect.squareup.com/v1/me/timecards \ -X POST \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "employee_id": "ormj0jJJZ5OZIzxrZYJI", "clockin_location_id": "PAA1RJZZKXBFG" "clockin_time": "2019-01-25T03:11:00-05:00", }'

A diagram showing the migration mapping from the Timecard object to the Shift object where the team member had no break.

Link to section

Capture a break

With the V1 Timecards API, it was necessary to create two TimeCard records for an employee who took a break on a shift. The first timecard was used to record the shift start to the clock out for the break. The second timecard recorded the clock in from the break to the clock out of the shift, or to the start of the next break.

When you migrate your code to use the Labor API, you get the existing shift and record breaks by updating the Shift with a Break object that records the time an employee clocks out for a break. Because Shift.breaks is an array, you can create a Break object for each break that an employee takes. For more information, see Add Breaks to a Shift.

Link to section

Labor: Clock out for a break

  1. Get a list of the break types created in the Seller Dashboard or by the CreateBreakType endpoint.

    curl https://connect.squareup.com/v2/labor/break-types? location_id=E78VDDVFW1EYX&limit=100 -X GET \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN' \
  2. Get the shift to update with a new break.

    curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27 -X GET \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN' \
  3. Update the shift with a Break object.

    A diagram showing the migration mapping from the Timecard object to the Shift object, with a break recorded in the Shift object.

Link to section

Employees.Timecards: Clock out for a break

  1. Get the timecard to close out.

    curl https://connect.squareup.com/v1/me/timecards/5M35N5FACFJTH \ -X GET \ -H 'Authorization: Bearer ACCESS_TOKEN' \
  2. Update the timecard with a clockout_time.

    curl https://connect.squareup.com/v1/me/timecards/5M35N5FACFJTH \ -X PUT \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "clockin_time": "2019-01-25T03:11:00-05:00", "clockout_time": "2019-01-25T04:00:00-05:00" }'
Link to section

Return from a break

With the Labor API, you update the Shift.breaks[0] with an end_at field. With the Employees.Timecards API, you create a new timecard for the second half of the shift.

Link to section

Labor: Return from a break

  1. Get the shift to update with a completed break.

    curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27 -X GET \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN' \
  2. Add an end_at field to the Break.

Link to section

Employees.Timecards: Return from a break

To clock in from a break, create a new timecard with a clockin_time set to the time that the employee returns from the break.

curl https://connect.squareup.com/v1/me/timecards \ -X POST \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "employee_id": "ormj0jJJZ5OZIzxrZYJI", "clockin_location_id": "PAA1RJZZKXBFG" "clockin_time": "2019-12-19T19:28:19Z", }'
Link to section

Clock out to end the shift

With the Labor API, you update the Shift with an end_at value. With the Employees.Timecards API, you update the timecard created for the second half of the shift with a clockout_time.

Link to section

Labor: Clock out of the shift

  1. Get the shift to close.

  2. Update the shift by adding an end_at field to the Shift.

Link to section

Employees.Timecards: Clock out of the shift

Update the timecard for the second half of the shift (created when an employee signed in from a break) with a clockout_time.

Update the timecard with a clockout_time.

curl https://connect.squareup.com/v1/me/timecards/8J35N3HACFJZZ \ -X PUT \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "clockin_time": "2019-12-19T19:28:19Z", "clockout_time": "2019-12-19T22:18:19Z" }'
Link to section

Common migration omissions

  • Employee setup. Employee wage level per job title is not set up in the Seller Dashboard. When creating a new shift, migrated code should look up the correct shift wage for an employee and the job title for the shift. If employee wages are not set up, an arbitrary wage level can be substituted.
  • Workweek setup. If your system calculates regular time, overtime, and doubletime pay for labor costs for a seller, you must have the start of the day in local time and the first weekday of the week. These values are stored in WorkweekConfig objects and set on the Seller Dashboard.
  • Break type setup. Create break type templates that define the expected duration of each break type. When adding a break to a shift, you must include the ID of the break type template, which can be set on the Seller Dashboard or by using the Labor API.