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

Labor API

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

You can subscribe to webhooks from any of your applications by opening the application details in your Developer Dashboard. Learn more from the Subscribe to Webhook Events guide.

  • 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 app requests the 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",
        "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, 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 an employee 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",
        "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