Labor, Bank Accounts, & CashDrawerShifts V2 APIs

This month we have several really great updates and releases. The V1 Timecards API functionality is now supported in the V2 Labor API. This change brings in more flexible models for handling shifts, recording time zones, and also V2 Webhook support.

We have also released our V2 CashDrawerShifts and V2 Bank Accounts APIs. CashDrawerShifts lets you easily manage cash drawer activity for creating bookkeeping reports for cash drawers paired with a Square Point of Sale. The Bank Accounts API allows you to retrieve information about the bank accounts linked to a Square account.

Labor API Updates

We’ve created improvements to the Labor API to support better functionality for what was previously handled by the V1 Timecards API. Here are some of the highlights of what has been improved from Timecards V1 to the Labor API:

• Flexible, multi-object Shift model — Labor API captures each employee shift as a parent Shift object with nested Break objects to capture multiple shift breaks, and a ShiftWage object to capture the hourly rate and job title of the employee on a given shift.
• Timezone recording — The time zone where an employee works a shift is recorded. This ensures that regular, overtime, and double-time calculation is correct across the timezones that an organization operates in.
• Labor Template objects — Square Labor API provides EmployeeWage objects for setting an employee's wage for a job title on future shifts for that job title, a BreakType template object to define standard break durations, and WorkweekConfig objects used for the calculation of overtime pay.
• V2 Webhook support — Webhook notifications are generated for all subscribing endpoints on all create, update, and delete operations on a Shift object. Use Webhooks to integrate with another system without polling for state changes.

For reference on how to migrate from V1 Timecards endpoints to V2 Labor API, check out our migration guide.

CashDrawerShifts API

The CashDrawerShifts API provides all of the functionality of the V1 Employees API CashDrawer endpoints, and adds these new features:

• Pagination — CashDrawerShifts API reporting endpoints provide pagination and sorting along with location and time range filtering.
• Cash drawer shift activity summary — The CashDrawerShiftSummary object is a cash drawer shift summary record that provides this shift summary information:
  • Shift start and end time
  • Opening cash amount
  • Expected closing cash amount
  • Actual closing cash amount
• Separate endpoint for events on a cash drawer shift — The ListCashDrawerShiftEvents endpoint provides reporting for getting the events on a cash drawer shift by ID. The V1 CashDrawerShift object contained a collection of all events on a cash drawer shift.

Bank Accounts API

The Bank Accounts API provides all of the functionality of the V1 Bank Accounts API and adds these new features:

• Pagination — V2 Bank Accounts API reporting endpoints now provide pagination.
• Webhooks — Provides V2 Webhook event notifications when a bank account is created, verified, or disabled.

Deprecations

With the release of these updates and new APIs, we will be deprecating the APIs that they are replacing. This includes:

• V1 Bank Accounts
• V1 CashDrawerShifts
• V1 Timecards

As with our previously announced deprecations, these APIs will be deprecated for approximately one year’s time and retired on 2021-02-26. A full list of deprecated APIs can be found here along with the timelines for deprecation periods.

Additionally, we are going to be releasing new SDKs for PHP and Node.js by Q2 2020 and Q3 2020, respectively. In anticipation of the release of these new SDKs, we are deprecating the existing Node.js and PHP SDKs. You can still safely use these SDKs during the depreciation period and they will continue to receive updates for any new APIs or functionality until the newer SDKs are released. Once the new Node.js and PHP SDKs are released, their older counterparts will move into security maintenance mode.

The SDKs themselves will continue to work indefinitely until the underlying APIs are retired or changed, at which point portions of the SDK may stop functioning. For a full list of API retirement dates, please see our Square API Lifecycle documentation.

If you ever have any questions, concerns, or just want some help in your migration or implementation of our APIs or SDKs, please reach out to us on Slack, Twitter, or through developer support.