Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Labor API

Use Webhooks to Integrate with a Payroll System

Subscribe to Labor API events Permalink Get a link to this section

The Labor API supports the following webhook events:

EventDescription
labor.shift.createdA worker started a shift.
Webhook notification data is packaged as a Shift.
labor.shift.updatedA shift was updated.
Typically a break was started or ended or a worker ended the shift.
Webhook notification data is packaged as a Shift.
labor.shift.deletedA shift was deleted.
Notification data includes the deleted shift ID and the isDeleted flag.

A webhook is a subscription where you specify which events you want to be notified about. For information about using webhooks, see Webhooks Overview. For a list of all webhook events supported by Square APIs, see see V2 Webhook Events Reference.

  • Shift created. labor.shift.created

  • Shift deleted. labor.shift.deleted

  • Shift updated. labor.shift.updated

Shift event notification body Permalink Get a link to this section

The event notification body includes properties that identify the notification and a data object for the current state of the Shift that is changed.

Read the type property to identify the notification as a create, update, or delete notification. The merchant_id property identifies the merchant/employer of the worker associated with the shift.

The current state of the Shift is carried by the value of data.object.shift.

To access a Shift represented by a notification, your application requests TIMECARDS_READ permission when authenticating with the OAuth flow.

Shift created event Permalink Get a link to this section

When a Shift is created (normally when an employee starts a shift), the webhook notification body includes a shift object representing the new shift.

If you use this event to synchronize an external payroll system with a Square Point of Sale timeclock, use the value of data.object.shift.id to create a unique ID for the created shift in the payroll system.

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "labor.shift.created",
  "event_id": "aeaaa5f6-c4fd-4e93-b688-71b50706266f",
  "created_at": "2019-10-29T17:26:16.808603647Z",
  "data": {
    "type": "labor",
    "id": "PY4YSMVKXFY9E",
    "object": {
      "shift": {
        "id": "PY4YSMVKXFY9E",
        "employee_id": "AnuhZhsN95oT8f-eCn9D",
        "team_member_id": "AnuhZhsN95oT8f-eCn9D",
        "location_id": "NAQ1FHV6ZJ8YV",
        "timezone": "Etc/UTC",
        "start_at": "2019-01-25T08:11:00Z",
        "end_at": "2019-01-25T18:11:00Z",
        "wage": {
          "title": "Barista",
          "hourly_rate": {
            "amount": 1100,
            "currency": "USD"
          }
        },
        "status": "OPEN",
        "version": 1,
        "created_at": "2019-11-06T19:14:55Z",
        "updated_at": "2019-11-06T19:14:55Z"
      }
    }
  }
}

Shifts are created using a Square POS terminal or by calling CreateShift.

Call GetShift with data.object.shift.id to get the newest version of the Shift represented by the notification. The Shift returned by the GetShift call returns an equal or greater version value as the notification data.object.shift.version.

Shift updated event Permalink Get a link to this section

Shifts are updated when a break is started, a break is ended, or the shift ends. Other actions that trigger this event include updates to any read/write property.

If you use this event to synchronize an external payroll system with a Square Point of Sale timeclock, use the value of data.object.shift.id to look up the shift in the payroll system.

The following example event body shows that a team member signed out for a break:

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "labor.shift.updated",
  "event_id": "aeaaa5f6-c4fd-4e93-b688-71b50706266f",
  "created_at": "2019-10-29T17:26:16.808603647Z",
  "data": {
    "type": "labor",
    "id": "PY4YSMVKXFY9E",
    "object": {
      "shift": {
        "id": "PY4YSMVKXFY9E",
        "employee_id": "AnuhZhsN95oT8f-eCn9D",
        "team_member_id": "AnuhZhsN95oT8f-eCn9D",
        "location_id": "NAQ1FHV6ZJ8YV",
        "timezone": "Etc/UTC",
        "start_at": "2019-01-25T08:11:00Z",
        "end_at": "2019-01-25T18:11:00Z",
        "wage": {
          "title": "Barista",
          "hourly_rate": {
            "amount": 1100,
            "currency": "USD"
          }
        },
        "breaks": [
          {
            "id": "0EGK74E8BJF62",
            "start_at": "2019-01-25T11:11:00Z",
            "break_type_id": "REGS1EQR1TPZ5",
            "name": "Tea Break",
            "expected_duration": "PT5M",
            "is_paid": true
          }
        ],
        "status": "ACTIVE",
        "version": 2,
        "created_at": "2019-11-06T19:14:55Z",
        "updated_at": "2019-11-06T19:14:55Z"
      }
    }
  }
}

Shifts are updated using a Square POS terminal or by calling UpdateShift.

Call GetShift with data.object.shift.id to get the newest version of the Shift represented by the notification. The Shift returned by the GetShift call returns an equal or greater version value as the notification data.object.shift.version.

Shift deleted event Permalink Get a link to this section

When a Shift is deleted, the data object provides the id of the deleted shift. If you use this event to synchronize an external payroll system with a Square Point of Sale timeclock, look up the ID of the deleted shift using the value of data.id.

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "labor.shift.deleted",
  "event_id": "aeaaa5f6-c4fd-4e93-b688-71b50706266f",
  "created_at": "2019-10-29T17:26:16.808603647Z",
  "data": {
    "type": "labor",
    "id": "PY4YSMVKXFY9E",
    "deleted": true
  }
}

Shifts are deleted by calling DeleteShift.