Monitor Square Terminals

Applies to: Terminal API | Devices API

Learn how to remotely monitor Square Terminals that are connected to the seller's storefront network.

Link to section

Requirements and limitations

  • Only Square Terminals running the Terminal API are represented in the Devices API.
  • Calls to a Devices API endpoint use OAuth to identify callers and associated merchants and require DEVICES_READ permission to access the device information.
  • The Devices API periodically provides updated device data, but not in real-time. If needed, use the PING Terminal action to get real-time information about a specific device.
Link to section

Monitoring devices

The ListDevices and GetDevice endpoints of the Devices API return read-only data about the seller's devices, such as network connectivity, battery level, and software version. This data is represented as a Device object for a given device. A Device object has a unique ID associated with the device (for example, device:b27e76da-2779-4a92-b076-affcbe3ae94d).

Use the device.created webhook to subscribe to events for information about when devices are created for a seller's account.

Link to section

List all devices for a given seller

The ListDevices endpoint doesn't require parameters, but supports filtering by location_id as well as parameters for paging through results (pagination).

The following request calls for a list of devices:

List devices

Link to section

Get information for a single device

Use the GetDevice endpoint to get detailed information for a specific device.

The following request example uses the device_id in the request path parameter with device:b27e76da-2779-4a92-b076-affcbe3ae94d as the device_id value being passed. Note that the device_id value includes the device: prefix and that the %3A characters represent the colon : in the request path parameter.

Get device

Link to section

Device information

A Device object contains:

  • The device ID.
  • The device’s overall status, which is AVAILABLE, NEEDS_ATTENTION, or OFFLINE.
  • A collection of device attributes representing the device as a whole. For example, these attributes can be the device type, model, and manufacturer.
  • An array of components, which are additional details associated with the device. For example, these components are comprised of the device type, the device's running application, batteries, card readers, and network interfaces.

Important

The Devices API doesn't support real-time heartbeat checks for a device. A device has a 15-minute interval to return an up-to-date status. If the device hasn't returned a status update after approximately 30 minutes, the device is likely offline.

The following response example is a single device object and its id, status, attributes, and components information. If you use ListDevices, the response returns a list of devices for the given seller along with each device's information.

Note that components represents a wrapper object for all of the component entries for the given component type.