CONNECT V1 MIGRATION

Migrate from the Connect v1 Timecards API

Migration overview
Permalink Get a link to this section

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.

Important dates
Permalink Get a link to this section

  • Deprecation: 2020-02-26

  • Retirement: 2021-02-26

If you need help
Permalink Get a link to this section

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.

General differences between the Timecards API and Labor API
Permalink Get a link to this section

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

Get v1 timecards information using the Labor API
Permalink Get a link to this section

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.

Discontinued functionality
Permalink Get a link to this section

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

Webhook and endpoint mapping
Permalink Get a link to this section

Webhooks
Permalink Get a link to this section

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.

Endpoints
Permalink Get a link to this section

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
CreateTimecard CreateShiftUsed to create a new employee shift.
DeleteTimecard DeleteShiftUsed to delete a shift.
ListTimecards SearchShiftsUsed 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.
RetrieveTimecard GetShiftUsed to retrieve a single shift by Shift.id.
UpdateTimecard UpdateShiftUsed to update a shift (such as, to record a break, clock out, or change a shift wage).

Migration examples
Permalink Get a link to this section

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

Clock in
Permalink Get a link to this section

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.

Labor API: Create a shift
Permalink Get a link to this section

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"
        }
      }
    }
  }'

Employees.Timecards: Create a timecard
Permalink Get a link to this section

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",
  }'

timecardv1-v2-nobreak 2

Capture a break
Permalink Get a link to this section

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.

Labor: Clock out for a break
Permalink Get a link to this section

  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.

    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"
              }
            }
        }
      }'
    
    

Final Shift with break

Employees.Timecards: Clock out for a break
Permalink Get a link to this section

  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"
      }'
    

Return from a break
Permalink Get a link to this section

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.

Labor: Return from a break
Permalink Get a link to this section

  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.

    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"
              }
            }
        }
      }'
    
    

Employees.Timecards: Return from a break
Permalink Get a link to this section

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",
  }'

Clock out to end the shift
Permalink Get a link to this section

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.

Labor: Clock out of the shift
Permalink Get a link to this section

  1. Get the shift to close.

  2. 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"
              }
            }
        }
      }'
    
    

Employees.Timecards: Clock out of the shift
Permalink Get a link to this section

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"
  }'

Common migration omissions
Permalink Get a link to this section

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