v1

latestOpenAPI 3.0.0Apache 2.02026-07-143281,4552.1 MB

Devices

ListDevices

List devices associated with the merchant. Currently, only Terminal API devices are supported.

get/v2/devices

Query parameters

cursorstring

A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. See Pagination for more information.

sort_order'DESC' | 'ASC'

The order (e.g., chronological or alphabetical) in which results from a request are returned.

The order in which results are listed.

ASC - Oldest to newest.
DESC - Newest to oldest (default).

limitinteger

The number of results to return in a single page.

location_idstring

If present, only returns devices at the target location.

Response

Success

cursorstring

The pagination cursor to be used in a subsequent request. If empty, this is the final response. See Pagination for more information.

Example response

{
  "cursor": "GcXjlV2iaizH7R0fMT6wUDbw6l4otigjzx8XOOspUKHo9EPLRByM",
  "devices": [
    {
      "attributes": {
        "manufacturer": "Square",
        "manufacturers_id": "995CS397A6475287",
        "merchant_token": "MLCHNZCBWFDZB",
        "model": "Square Terminal (1st Gen, v2)",
        "name": "Square Terminal 5287",
        "type": "TERMINAL",
        "updated_at": "2025-08-19T13:04:56.335762883Z",
        "version": "5.57.0067"
      },
      "components": [
        {
          "application_details": {
            "application_type": "TERMINAL_API",
            "session_location": "LMN2K7S3RTOU3",
            "version": "6.77"
          },
          "type": "APPLICATION"
        },
        {
          "card_reader_details": {
            "version": "4.1.51"
          },
          "type": "CARD_READER"
        },
        {
          "battery_details": {
            "external_power": "AVAILABLE_CHARGING",
            "visible_percent": 77
          },
          "type": "BATTERY"
        },
        {
          "type": "WIFI",
          "wifi_details": {
            "active": true,
            "ip_address_v4": "10.0.0.7",
            "secure_connection": "WPA/WPA2 PSK",
            "signal_strength": {
              "value": 2
            },
            "ssid": "Staff Network"
          }
        },
        {
          "ethernet_details": {
            "active": false
          },
          "type": "ETHERNET"
        }
      ],
      "id": "device:995CS397A6475287",
      "status": {
        "category": "AVAILABLE"
      }
    },
    {
      "attributes": {
        "manufacturer": "Square",
        "manufacturers_id": "998WS21803L03559",
        "merchant_token": "MLCHXZCBWFGDW",
        "model": "Square Handheld (1st Gen, v1)",
        "name": "Square Terminal 3559",
        "type": "HANDHELD",
        "updated_at": "2025-08-19T12:39:56.335742073Z",
        "version": "7.21.0017"
      },
      "components": [
        {
          "application_details": {
            "application_type": "TERMINAL_API",
            "session_location": "LMN2K7S3RTOU3",
            "version": "6.77"
          },
          "type": "APPLICATION"
        },
        {
          "card_reader_details": {
            "version": "4.5.58"
          },
          "type": "CARD_READER"
        },
        {
          "battery_details": {
            "external_power": "AVAILABLE_CHARGING",
            "visible_percent": 22
          },
          "type": "BATTERY"
        },
        {
          "type": "WIFI",
          "wifi_details": {
            "active": true,
            "ip_address_v4": "10.0.0.7",
            "secure_connection": "WPA/WPA2 PSK",
            "signal_strength": {
              "value": 2
            },
            "ssid": "Staff Network"
          }
        },
        {
          "ethernet_details": {
            "active": false
          },
          "type": "ETHERNET"
        }
      ],
      "id": "device:998WS21803L03559",
      "status": {
        "category": "NEEDS_ATTENTION"
      }
    }
  ]
}