The Devices API allows you to retrieve and manage information about Square hardware devices, including Square Terminals and card readers.
Overview
The Devices client provides methods to:
- List all devices associated with a merchant
- Retrieve details about a specific device
- View device components (battery, WiFi, card reader, etc.)
Client Initialization
import (
"context"
"github.com/square/square-go-sdk/v3"
"github.com/square/square-go-sdk/v3/core"
)
client := square.NewClient(
&core.RequestOptions{
Token: "YOUR_ACCESS_TOKEN",
},
)
Methods
List Devices
Retrieves a list of devices associated with the merchant. Currently, only Terminal API devices are supported.
request := &square.ListDevicesRequest{
Cursor: square.String("cursor_value"),
SortOrder: square.SortOrderDesc.Ptr(),
Limit: square.Int(10),
LocationID: square.String("LOCATION_ID"),
}
response, err := client.Devices.List(context.TODO(), request)
if err != nil {
// Handle error
}
for _, device := range response.Devices {
fmt.Printf("Device: %s (Type: %s)\n", *device.Attributes.Name, device.Attributes.Type)
}
A pagination cursor from a previous call. Provide this to retrieve the next set of results.
The order in which results are listed:
ASC: Oldest to newestDESC: Newest to oldest (default)
The number of results to return in a single page
If present, only returns devices at the target location
Array of device objects
A unique synthetic identifier for the device
Device information including type, manufacturer, model, and version
List of device components (battery, WiFi, card reader, etc.)
The current status of the device
Get Device
Retrieves details about a specific device.
request := &square.GetDevicesRequest{
DeviceID: "DEVICE_ID",
}
response, err := client.Devices.Get(context.TODO(), request)
if err != nil {
// Handle error
}
device := response.Device
fmt.Printf("Device Name: %s\n", *device.Attributes.Name)
fmt.Printf("Manufacturer: %s\n", device.Attributes.Manufacturer)
fmt.Printf("Model: %s\n", *device.Attributes.Model)
// Check device status
if device.Status != nil && device.Status.Category != nil {
fmt.Printf("Status: %s\n", *device.Status.Category)
}
// Inspect components
for _, component := range device.Components {
fmt.Printf("Component Type: %s\n", component.Type)
}
The unique ID for the desired device
The requested device object
Response Types
Device
Represents a Square hardware device.
A synthetic identifier for the device (generated from key device fields)
A collection of attributes representing the device
List of components applicable to the device
The current operational status of the device
DeviceAttributes
The device type:
TERMINAL: A Square Terminal deviceHANDHELD: A handheld device
The maker of the device (e.g., “Square”)
The specific model of the device
A seller-specified name for the device
The manufacturer-supplied identifier (often a serial number)
The RFC 3339 timestamp of the most recent update to device information
The current version of software installed on the device
Component
Represents a device component (battery, WiFi, card reader, etc.).
The type of component:
APPLICATION: Software applicationCARD_READER: Card reader hardwareBATTERY: Battery componentWIFI: WiFi interfaceETHERNET: Ethernet interfacePRINTER: Printer component
Details for APPLICATION components
Details for CARD_READER components
Details for BATTERY components
visible_percent: Battery percentageexternal_power: Power connection status
Details for WIFI components
active: Whether WiFi is activessid: Network nameip_address_v4: IPv4 addresssignal_strength: Signal strength measurement
Details for ETHERNET components
active: Whether Ethernet is activeip_address_v4: IPv4 address
DeviceStatus
The status category:
AVAILABLE: Device is available and operationalNEEDS_ATTENTION: Device requires attentionOFFLINE: Device is offline
Use Cases
Check Device Battery Status
response, err := client.Devices.Get(context.TODO(), &square.GetDevicesRequest{
DeviceID: "DEVICE_ID",
})
if err != nil {
log.Fatal(err)
}
for _, component := range response.Device.Components {
if component.Type == square.ComponentComponentTypeBattery {
if component.BatteryDetails != nil {
fmt.Printf("Battery: %d%%\n", *component.BatteryDetails.VisiblePercent)
if component.BatteryDetails.ExternalPower != nil {
fmt.Printf("Power Status: %s\n", *component.BatteryDetails.ExternalPower)
}
}
}
}
List Devices at a Specific Location
request := &square.ListDevicesRequest{
LocationID: square.String("LOCATION_ID"),
Limit: square.Int(20),
}
response, err := client.Devices.List(context.TODO(), request)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Found %d devices\n", len(response.Devices))
for _, device := range response.Devices {
fmt.Printf("- %s (Model: %s)\n",
*device.Attributes.Name,
*device.Attributes.Model,
)
}
Check Network Connectivity
response, err := client.Devices.Get(context.TODO(), &square.GetDevicesRequest{
DeviceID: "DEVICE_ID",
})
if err != nil {
log.Fatal(err)
}
for _, component := range response.Device.Components {
switch component.Type {
case square.ComponentComponentTypeWifi:
if component.WifiDetails != nil && component.WifiDetails.Active != nil {
if *component.WifiDetails.Active {
fmt.Printf("WiFi: Connected to %s\n", *component.WifiDetails.Ssid)
fmt.Printf("IP: %s\n", *component.WifiDetails.IPAddressV4)
}
}
case square.ComponentComponentTypeEthernet:
if component.EthernetDetails != nil && component.EthernetDetails.Active != nil {
if *component.EthernetDetails.Active {
fmt.Printf("Ethernet: Connected\n")
fmt.Printf("IP: %s\n", *component.EthernetDetails.IPAddressV4)
}
}
}
}
Error Handling
response, err := client.Devices.Get(context.TODO(), request)
if err != nil {
// Check for API errors
if response != nil && len(response.Errors) > 0 {
for _, e := range response.Errors {
fmt.Printf("Error: %s - %s\n", e.Category, e.Detail)
}
}
return err
}
