Learn how to migrate your Connect V1 Timecard API code to the Square Labor API.
Connect V1 Migration

Migrate from the Connect V1 Timecards API

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.

  • Deprecation: 2020-02-26

  • Retirement: 2021-02-26

If you need help migrating to Square APIs or need more time to complete your migration, contact Developer Support, join our Slack, or reach out to your Square Account Manager.

  • 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.

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.

  • 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.

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.

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).

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

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.

A diagram showing the migration mapping from the Timecard object to the Shift object where the team member had no 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.

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

  2. Get the shift to update with a new break.

  3. Update the shift with a Break object.

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    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.

  1. Get the timecard to close out.

  2. Update the timecard with a clockout_time.

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.

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

  2. Add an end_at field to the Break.

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    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"
              }
            }
        }
      }'
    

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.

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.

  1. Get the shift to close.

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

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    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"
              }
            }
        }
      }'
    

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.

  • 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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.