Labor API

Migrate from Employees to Team Members

This topic describes how to migrate application code from tracking Square (v2) Employees API (deprecated) Employee labor shifts to tracking shifts for Square Team API TeamMember objects.

Migration overview
Endpoints
Object mapping
Field mapping
Update the Labor API for team_member_id

Link to section
Migration overview

The Labor API (version 2020-08-26) continues to support the deprecated Employee object during the deprecation period of the Employees API. Use this guide to migrate your Labor API code to using the Team API TeamMember object when making calls with the Labor API version 2020-08-26 or later.

Link to section
Important dates

Deprecation: 2020-08-26
Retirement: 2021-08-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 Slack, or reach out to your Square account manager.

Link to section
Endpoints

The Team API and Labor API wage setting endpoints replace the employee roll endpoints in the v1 Employees API.

The Square Labor API endpoints for employee wages are deprecated and replaced with team member wage endpoints as shown in the following table:

Deprecated Labor endpoint	Replacement
GetEmployeeWage	GetTeamMemberWage
ListEmployeeWages	ListTeamMemberWages

Link to section
Object mapping

The Team API provides wage setting objects for each team member to replace the employee wage object for an employee. These objects are returned by the endpoints noted in the previous section.

Deprecated object	Replacement
EmployeeWage	TeamMemberWage

Link to section
Field mapping

The Shift and ShiftFilter objects are updated to include team member ID fields. The employee ID fields remain in the objects to support the Employee object until it is retired.

Deprecated field	Replacement
`Shift.employee_id`	`Shift.team_member_id`
`ShiftFilter.employee_ids`	`ShiftFilter.team_member_ids`

Link to section
Update the Labor API for team_member_id

To update your Labor API application code, change the references of employee_id to team_member_id in each request call. No other functionalities have been affected here.

Link to section
List team member wages

Developers must reference team_member_id in the request for the response to return team_member_id populated with the same employee ID. Note that an employee ID value can be set as the value of the team_member_id.

Example request

Labor request with Employee_id

List Employee Wages

curl https://connect.squareupsandbox.com/v2/labor/employee-wages?employee_id=EMPLOYEE_ID \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Labor request with Team_member_id

List Team Member Wages

curl https://connect.squareupsandbox.com/v2/labor/team-member-wages?team_member_id=TEAM_MEMBER_ID \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Example response

Labor Employee_id response

1
2
3
4
5
6
7
8
9
10
11
12

{
    "employee_wages": [{
        "id": "employee_wage_id",
        "employee_id": "employeeid",
        "title": "Chef",
        "hourly_rate": {
            "amount": 6000,
            "currency": "USD"
        }
    }],
    "cursor": "CURSOR"
}

Labor Team_member_id response

1
2
3
4
5
6
7
8
9
10
11

{
    "team_member_wages": [{
        "id": "employee_wage_id",
        "team_member_id": "employeeid",
        "title": "Chef",
        "hourly_rate": {
            "amount": 6000,
            "currency": "USD"
        }
    }]
}

Link to section
Get team member wage

The response of team member wage returns a payload with team_member_id populated.

Example request

Labor API request with Employee_id

Get Employee Wage

curl https://connect.squareupsandbox.com/v2/labor/employee-wages/{id} \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Labor API request with Team_member_id

Get Team Member Wage

curl https://connect.squareupsandbox.com/v2/labor/team-member-wages/TEAM_MEMBER_ID \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Example response

Labor API Employee_id response

1
2
3
4
5
6
7
8
9
10
11

{
    "employee_wage": {
        "id": "employee_wage_id",
        "employee_id": "employeeid",
        "title": "Chef",
        "hourly_rate": {
            "amount": 6000,
            "currency": "USD"
        }
    }
}

Labor Team_member_id response

1
2
3
4
5
6
7
8
9
10
11

{
  "team_member_wage": {
    "id": "pXS3qCv7BERPnEGedM4S8mhm",
    "team_member_id": "33fJchumvVdJwxV0H6L9",
    "title": "Manager",
    "hourly_rate": {
      "amount": 2000,
      "currency": "USD"
    }
  }
}

Link to section
Create shift

External developers can reference either employee_id or team_member_id in the request, and the response returns both employee_id and team_member_id populated with the same employee ID.

Example request

Labor request with Employee_id

Create Shift

1
2
3
4
5
6
7
8
9
10
11
12

curl https://connect.squareupsandbox.com/v2/labor/shifts \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "shift": {
      "employee_id": "employee_id",
      "start_at": "2020-07-01T08:43:00Z",
      "location_id": "location_id"
    }
  }'

Labor request with Team_member_id

Create Shift

1
2
3
4
5
6
7
8
9
10
11
12

curl https://connect.squareupsandbox.com/v2/labor/shifts \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "shift": {
      "team_member_id": "employee_id",
      "start_at": "2020-07-01T08:43:00Z",
      "location_id": "location_id"
    }
  }'

Example response

Regardless of which of the previous requests are made, the response has an employee_id and a team_member_id, both of which contain the same value.

When the Employee API is retired, the employee_id is no longer returned.

Labor response with Team_member_id

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
    "shift": {
        "id": "shift_id",
        "employee_id": "employee_token",
        "team_member_id": "employee_token",
        "location_id": "location_id",
        "start_at": "2020-07-01T08:43:00Z",
        "wage": {
            "hourly_rate": {
                "amount": 0,
                "currency": "USD"
            }
        },
        "status": "OPEN",
        "version": 1,
        "created_at": "2020-07-01T20:47:55Z",
        "updated_at": "2020-07-01T20:47:55Z"
    }
}

Link to section
Update shift

External developers can reference either employee_id or team_member_id in the request, and the response returns both employee_id and team_member_id populated with the same employee ID.

Example request Labor request with Employee_id

Update Shift

1
2
3
4
5
6
7
8
9
10
11
12
13

curl https://connect.squareupsandbox.com/v2/labor/shifts/{id} \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "shift": {
      "employee_id": "employee_token",
      "start_at": "2020-07-01T08:43:00Z",
      "end_at": "2020-07-01T12:43:00Z",
      "location_id": "location_id"
    }
  }'

Labor request with Team_member_id

Update Shift

1
2
3
4
5
6
7
8
9
10
11
12
13

curl https://connect.squareupsandbox.com/v2/labor/shifts/{id} \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "shift": {
      "team_member_id": "employee_token",
      "start_at": "2020-07-01T08:43:00Z",
      "end_at": "2020-07-01T12:43:00Z",
      "location_id": "location_id"
    }
  }'

Example response

Regardless of which of the previous requests are made, the response has an employee_id and a team_member_id, both of which contain the same value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
    "shift": {
        "id": "shift_id",
        "employee_id": "employee_token",
        "team_member_id": "employee_token",
        "location_id": "location_id",
        "start_at": "2020-07-01T08:43:00Z",
        "end_at": "2020-07-01T12:43:00Z",
        "wage": {
            "hourly_rate": {
                "amount": 0,
                "currency": "USD"
            }
        },
        "status": "CLOSED",
        "version": 2,
        "created_at": "2020-07-01T20:47:55Z",
        "updated_at": "2020-07-01T20:47:55Z"
    }
}

Link to section
Get shift

The response of shift returns a payload with both employee_id and team_member_id populated.

Example responses

Regardless of which of the previous requests are made, the response has an employee_id and a team_member_id, both of which contain the same value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
    "shift": {
        "id": "shift_id",
        "employee_id": "employee_token",
        "team_member_id": "employee_token",
        "location_id": "location_id",
        "start_at": "2020-07-01T08:43:00Z",
        "end_at": "2020-07-01T12:43:00Z",
        "wage": {
            "hourly_rate": {
                "amount": 0,
                "currency": "USD"
            }
        },
        "status": "CLOSED",
        "version": 2,
        "created_at": "2020-07-01T20:47:55Z",
        "updated_at": "2020-07-01T20:47:55Z"
    }
}

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

Docs

Migrate from Employees to Team Members

On this page

On this page

Link to section
Migration overview

Link to section
Important dates

Link to section
If you need help

Link to section
Endpoints

Link to section
Object mapping

Link to section
Field mapping

Link to section
Update the Labor API for team_member_id

Link to section
List team member wages

Link to section
Get team member wage

Link to section
Create shift

Note

Link to section
Update shift

Link to section
Get shift

On this page

Docs

Migrate from Employees to Team Members

On this page

On this page

Link to section Migration overview

Link to section Important dates

Link to section If you need help

Link to section Endpoints

Link to section Object mapping

Link to section Field mapping

Link to section Update the Labor API for team_member_id

Link to section List team member wages

Link to section Get team member wage

Link to section Create shift

Note

Link to section Update shift

Link to section Get shift

On this page

Link to section
Migration overview

Link to section
Important dates

Link to section
If you need help

Link to section
Endpoints

Link to section
Object mapping

Link to section
Field mapping

Link to section
Update the Labor API for team_member_id

Link to section
List team member wages

Link to section
Get team member wage

Link to section
Create shift

Link to section
Update shift

Link to section
Get shift