Labor API

Build with the Labor API

Prerequisites and assumptions Permalink Get a link to this section

This topic provides step-by-step guidance for integrating with the Labor API. For information about how the Labor API works, see How It Works.

To use the Labor API, the following must be true:

  • You have a Square account. Create a Square account in minutes if you do not already have one.

  • You have added team members to at least one location in the Square Seller Dashboard.

This topic also makes the following assumptions:

  • The Seller Dashboard for your account has at least one active team member.

  • You have assigned at least one wage type per team member in the Seller Dashboard.

Did you know?

You can assign wage types to a team member by using the Team API.

Information you need Permalink Get a link to this section

To use the steps in this topic, you need:

  • A valid access token. You should test with Sandbox credentials whenever possible. For more information, see Square API Access Tokens.

  • An active location ID. Copy a developer account location ID from the Locations page of your Square application in the Developer Dashboard or set the Developer Dashboard to Sandbox mode and then copy a Sandbox location ID.

Shift time tracking at a glance Permalink Get a link to this section

This topic walks you through the process of starting and ending a team member shift:

Start a shift

  1. Configure the Labor API with a valid access token and location ID.

  2. Get a team member ID.

  3. Get the wage type for the job to be done on the shift.

  4. Check for a previous open shift for the team member.

  5. Create and send a CreateShift request to start a shift.

End a shift

  1. Search for the open shift.

  2. Update the open shift with an end time to end it.

Configure the Labor API Permalink Get a link to this section

Before you can use the Labor API, you must set the location ID where the API is used and then authorize the API to access Shift and TeamMember resources for that location.

Step 1: Get your authorization token Permalink Get a link to this section

  1. Open the Developer Dashboard and select an application. The Credentials page for the selected application is shown.

  2. Set the Developer Dashboard mode to Production for a Production environment access token or Sandbox for a Sandbox environment access token.

  3. Copy the Access Token in the Credentials section of the page.

Store the copied access token in a secure location. Developers can use that token in their own applications to get full API access to your Square account.

Did you know?

For more secure access to your Square account, use an OAuth token. The OAuth flow enforces security in two ways:

  • Challenges users to identify themselves before granting access to a Square account.

  • Limits the scope of access to a Square account and only after the authenticated user authorizes access.

If you are using an OAuth access token, request EMPLOYEES_READ and TIMECARDS_WRITE permissions.

Step 2: Get your location ID Permalink Get a link to this section

All team member shifts processed with the Labor API must be associated with a valid location ID for the associated Square account. Use the Locations API to find your location ID:

Search for the location where the team member shift is starting. Use the Location.id for the Labor API operations in this topic.

List Locations
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/locations \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The response contains all locations for the seller:

{
  "locations": [
    {
      "id": "VJN4XSBFTVPK9",
      "name": "Default Test Account",
      "timezone": "Etc/UTC",
      "capabilities": [
        "CREDIT_CARD_PROCESSING"
      ],
      "status": "ACTIVE",
      "created_at": "2019-07-19T23:37:58Z",
      "merchant_id": "{{MERCHANT_ID}}",
      "country": "US",
      "language_code": "en-US",
      "currency": "USD",
      "type": "PHYSICAL",
      "business_hours": {},
      "mcc": "7299"
    }
  ]
}

Open a new shift Permalink Get a link to this section

Step 1: Get a team member to start the shift Permalink Get a link to this section

Use the Team API to retrieve a list of active team members for a location and select a team member from the list. Use the following cURL command to get active team members for a location:

Search Team Members
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareup.com/v2/team-members/search \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "0G5P3VGACMMQZ"
        ],
        "status": "ACTIVE"
      }
    },
    "limit": 3
  }'

The response carries an array of TeamMember objects:

{
  "team_members": [
    {
      "id": "-3oZQKPKVk6gUXU_V5Qa",
      "reference_id": "12345678",
      "is_owner": false,
      "status": "ACTIVE",
      "given_name": "Johnny",
      "family_name": "Cash",
      "email_address": "johnny_cash@squareup.com",
      "created_at": "2019-07-10T17:26:48Z",
      "updated_at": "2020-04-28T21:49:28.957Z",
      "assigned_locations": {
        "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
      }
    },
    {
      "id": "1AVJj0DjkzbmbJw5r4KK",
      "reference_id": "abcded",
      "is_owner": false,
      "status": "ACTIVE",
      "given_name": "Lombard",
      "family_name": "Smith",
      "phone_number": "+14155552671",
      "created_at": "2020-03-24T18:14:01.127Z",
      "updated_at": "2020-06-09T17:38:05.423Z",
      "assigned_locations": {
        "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
      }
    },
    {
      "id": "2JCmiJol_KKFs9z2Evim",
      "is_owner": false,
      "status": "ACTIVE",
      "given_name": "Monica",
      "family_name": "Sway",
      "created_at": "2020-03-24T01:09:25.010Z",
      "updated_at": "2020-03-24T01:09:25.010Z",
      "assigned_locations": {
        "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
      }
    }
  ],
  "cursor": "N:9UglUjOXQ13-hMFypCft"
}

Step 2: Get the team member wage types Permalink Get a link to this section

Use the Team API to get the wage settings created for a team member.

A TeamMember can have multiple wage types and job titles. To assign the correct wage to a shift, get all the WageSetting objects for the team member and find the wage type for the job that the team member is performing in this shift.

Did you know?

The first WageSetting in the set of returned items is the default team member wage. Use the default wage unless you are choosing a WageSetting based on a matching job title.

Retrieve Wage Setting
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/team-members/1yJlHapkseYnNPETIU1B/wage-setting \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The response carries an array of the WageSetting objects associated with a team member ID:

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

Step 3: Check for an open shift Permalink Get a link to this section

A new shift cannot be started for a team member until the previous shift is ended.

The following shift search request asks for a set of shifts with the following instructions:

  • Shifts for one specified team member.

  • At a specified location.

  • With shifts whose status is OPEN.

This filter always returns zero or one Shift. A team member can have a maximum of one open shift.

Search Shifts
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareup.com/v2/labor/shifts/search \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "status": "OPEN",
        "team_member_ids": [
          "A_TEAM_MEMBER_ID"
        ]
      }
    }
  }'

The response to the shift search request is an empty object if the team member does not have an OPEN shift:

{}

Step 4: Build a shift object Permalink Get a link to this section

To create a new shift, use the location ID, team member ID, and WageSetting hourly rate to set values in a new ShiftWage. The shift start_at field can be set to local time or GMT. If you use GMT, the Square Labor endpoint calculates the local time based on the location of the shift.

POST a new shift using cURL at the command line.

Create Shift
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
curl https://connect.squareup.com/v2/labor/shifts \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "UUID",
    "shift": {
      "team_member_id": "A_TEAM_MEMBER_ID",
      "location_id": "YOUR_LOCATION_ID",
      "start_at": "2019-02-05T12:00:00Z",
      "wage": {
        "title": "Photographer",
        "hourly_rate": {
          "amount": 4500,
          "currency": "USD"
        }
      }
    }
  }'

Close the shift Permalink Get a link to this section

Step 1: Get the shift to close Permalink Get a link to this section

Get the open shift for the team member by using the example in Step 3.

The response to the shift search request is an array of Shift objects that match the filter criteria:

{
    "shifts": [
        {
            "id": "3DBHNF9E8CG27",
                        "team_member_id": "A_TEAM_MEMBER_ID",
            "location_id": "YOUR_LOCATION_ID",
            "timezone": "America/Los_Angeles",
            "start_at": "2018-10-04T04:00:00-07:00",
...
            "status": "OPEN",
            "version": 1,
            "created_at": "2019-02-20T01:28:49Z",
            "updated_at": "2019-02-20T01:28:49Z"
        }
    ]
}

Step 2: Update the shift Permalink Get a link to this section

To close a shift, an end_at field is added to the open shift. If the shift has an open break, it must be closed before the shift can be closed.

Update 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
curl https://connect.squareup.com/v2/labor/shifts/{id} \
  -X PUT \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "shift": {
      "id": "3DBHNF9E8CG27",
      "team_member_id": "aq8XS-F0-VA0UrgH6h3w",
      "location_id": "YOUR_LOCATION_ID",
      "timezone": "America/Los_Angeles",
      "start_at": "2018-10-16T04:00:00-07:00",
      "end_at": "2018-10-16T12:00:00Z",
      "wage": {
        "title": "Photographer",
        "hourly_rate": {
          "amount": 4500,
          "currency": "USD"
        }
      },
      "status": "OPEN",
      "version": 3,
      "created_at": "2019-02-21T20:22:10Z",
      "updated_at": "2019-02-21T20:24:34Z"
    }
  }'

Before you POST the updated shift, look for an array of Break objects that are present if the employee took any breaks during the shift. If you find these object, confirm that they contain end_at properties and that those properties are not null.

The response is an updated version of the shift object with a CLOSED status and an incremented version number:

{
    "shift": {
        "id": "3DBHNF9E8CG27",
...
        "start_at": "2018-10-16T04:00:00-07:00",
        "end_at": "2018-10-16T12:00:00-07:00",
...
        "status": "CLOSED",
        "version": 4,
...
    }
}

Related topics Permalink Get a link to this section