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

You can subscribe to webhooks from any of your applications by opening the application details in the Developer Dashboard. For more information, see Subscribe to Events.

  • 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.