Learn about migrating your Labor API application code to reference team members in the Team API.
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.
- Deprecation: 2020-08-26
- Retirement: 2021-08-26
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.
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 |
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 |
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 |
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.
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
Labor request with Team_member_id
List team member wages
Example response
Labor Employee_id response
{
"employee_wages": [{
"id": "employee_wage_id",
"employee_id": "employeeid",
"title": "Chef",
"hourly_rate": {
"amount": 6000,
"currency": "USD"
}
}],
"cursor": "CURSOR"
}
Labor Team_member_id response
{
"team_member_wages": [{
"id": "employee_wage_id",
"team_member_id": "employeeid",
"title": "Chef",
"hourly_rate": {
"amount": 6000,
"currency": "USD"
}
}]
}
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
Labor API request with Team_member_id
Get team member wage
Example response
Labor API Employee_id response
{
"employee_wage": {
"id": "employee_wage_id",
"employee_id": "employeeid",
"title": "Chef",
"hourly_rate": {
"amount": 6000,
"currency": "USD"
}
}
}
Labor Team_member_id response
{
"team_member_wage": {
"id": "pXS3qCv7BERPnEGedM4S8mhm",
"team_member_id": "33fJchumvVdJwxV0H6L9",
"title": "Manager",
"hourly_rate": {
"amount": 2000,
"currency": "USD"
}
}
}
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
Labor request with Team_member_id
Create shift
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.
Note
When the Employee API is retired, the employee_id
is no longer returned.
Labor response with Team_member_id
{
"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"
}
}
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
Labor request with Team_member_id
Update shift
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.
{
"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"
}
}
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.
{
"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"
}
}