CONNECT V1 MIGRATION

Migrate from Connect v1 Timecards API

Migration guidance for updating Connect v1 Timecards API code to the Square Labor API.

Migration overview
Permalink Get a link to this section

The Connect v1 Timecards API lets developers capture employee work hours. The Square Labor API captures work hours including breaks. Labor also 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, please contact Developer Support, join our Slack, or reach out to your Square Account Manager.

General differences between Timecards and Labor
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 that an organization operates in.

  • Labor Template objects — 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 for the calculation of overtime pay.

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

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

You can use the Labor API to retrieve v1 timecards 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. Read the Square Timecards FAQ to learn about calculating labor costs.

  • The audit functionality of the v1TimeCardEvent object is not available in the Square Labor API. To replicate this functionality, use the v2 Webhook notifications for the Labor API to update a log in your system. The v1TimeCardEvent.event_type indicated 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 the Labor API change the state of a Shift. Read Labor Webhooks to learn more.

Endpoints
Permalink Get a link to this section

  • Square Labor API endpoints replace the Timecards endpoints in v1Employees API. 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 Webhook 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. For example, 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 1 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 2 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 2nd 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. Shift.breaks is an array so you can create a Break object for each break that an employee takes. See Add Shifts to a Break for more information.

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'             \
  1. 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'             \
  1. 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' \
  1. 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 2nd 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'             \
  1. 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 2nd 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 2nd half of the shift (created when employee signed in from their 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 was 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 their job title for the shift. If employee wages are not set up, an arbitrary wage level can be substituted.

  • Breaks and overtime setup

    Workweek setup — If your system calculates regular time, overtime, and doubletime pay for labor costs for a seller, you must have the start of 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. Set on the seller dashboard or by using the Labor API.