Migrate from the Connect V1 Timecards API

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 endpoint	Replacement	Usage
CreateTimecard	CreateShift	Used to create a new employee shift.
DeleteTimecard	DeleteShift	Used to delete a shift.
ListTimecards	SearchShifts	Used to retrieve a filtered and sorted set of shifts.
ListTimecardEvents	No direct replacement	Use 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.
RetrieveTimecard	GetShift	Used to retrieve a single shift by `Shift.id`.
UpdateTimecard	UpdateShift	Used 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

curl https://connect.squareup.com/v2/labor/shifts \
  -X POST \
  -H 'Square-Version: 2019-12-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
    "idempotency_key": "HIDSNG5KS478L",
    "shift": {
      "employee_id": "ormj0jJJZ5OZIzxrZYJI",
      "location_id": "PAA1RJZZKXBFG",
      "start_at": "2019-01-25T03:11:00-05:00",
      "wage": {
        "title": "Barista",
        "hourly_rate": {
          "amount": 1100,
          "currency": "USD"
        }
      }
    }
  }'

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

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'             \

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'             \

Update the shift with a Break object.

curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27  \
 -X PUT \
 -H 'Content-Type: application/json'                               \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'             \
 -D '{
    "shift": {
        "id": "3DBHNF9E8CG27",
        "employee_id": "ormj0jJJZ5OZIzxrZYJI",
        "location_id": "PAA1RJZZKXBFG",
        "start_at": "2019-01-25T03:11:00-05:00",
        "breaks": [
            {
                "start_at": "2019-01-25T04:00:00-05:00",
                "break_type_id": "Y32XW5N9JHHW3",
                "name": "2nd Breakfast",
                "expected_duration": "PT10M",
                "is_paid": true
            }
        ],
        "wage": {
          "title": "Barista",
          "hourly_rate": {
            "amount": 1100,
            "currency": "USD"
          }
        }
    }
  }'

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

Get the timecard to close out.

curl https://connect.squareup.com/v1/me/timecards/5M35N5FACFJTH  \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN' \

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

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'             \

Add an end_at field to the Break.

curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27  \
 -X PUT \
 -H 'Content-Type: application/json'                               \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'             \
 -D '{
    "shift": {
        "id": "3DBHNF9E8CG27",
        "employee_id": "ormj0jJJZ5OZIzxrZYJI",
        "location_id": "PAA1RJZZKXBFG",
        "start_at": "2019-01-25T03:11:00-05:00",
        "breaks": [
            {
                "start_at": "2019-01-25T04:00:00-05:00",
                "end_at": "2019-01-25T04:10:00-05:00", 
                "break_type_id": "Y32XW5N9JHHW3",
                "name": "2nd Breakfast",
                "expected_duration": "PT10M",
                "is_paid": true
            }
        ],
        "wage": {
          "title": "Barista",
          "hourly_rate": {
            "amount": 1100,
            "currency": "USD"
          }
        }
    }
  }'

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

Get the shift to close.

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

curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27  \
 -X PUT \
 -H 'Content-Type: application/json'                               \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'             \
 -D '{
    "shift": {
        "id": "3DBHNF9E8CG27",
        "employee_id": "ormj0jJJZ5OZIzxrZYJI",
        "location_id": "PAA1RJZZKXBFG",
        "start_at": "2019-01-25T03:11:00-05:00",
        "end_at": "2019-01-25T11:11:00-05:00",
        "breaks": [
            {
                "start_at": "2019-01-25T04:00:00-05:00",
                "end_at": "2019-01-25T04:10:00-05:00", 
                "break_type_id": "Y32XW5N9JHHW3",
                "name": "2nd Breakfast",
                "expected_duration": "PT10M",
                "is_paid": true
            }
        ],
        "wage": {
          "title": "Barista",
          "hourly_rate": {
            "amount": 1100,
            "currency": "USD"
          }
        }
    }
  }'

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.

Docs

Migrate from the Connect V1 Timecards API

On this page

On this page

Migration overview

Important dates

If you need help

General differences between the Timecards API and Labor API

Get V1 timecards information using the Labor API

Discontinued functionality

Webhook and endpoint mapping

Webhooks

Endpoints

Migration examples

Clock in

Labor API: Create a shift

Employees.Timecards: Create a timecard

Capture a break

Labor: Clock out for a break

Employees.Timecards: Clock out for a break

Return from a break

Labor: Return from a break

Employees.Timecards: Return from a break

Clock out to end the shift

Labor: Clock out of the shift

Employees.Timecards: Clock out of the shift

Common migration omissions

On this page