You are viewing an old version of the API

All Versions

List customers

GET /v2/customers

Lists customer profiles associated with a Square account.

Under normal operating conditions, newly created or updated customer profiles become available for the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.

Permissions

CUSTOMERS_READ

Guide

Retrieve a list of customer profiles Try in API Explorer

Query Parameters

Example code

Name	Description
`cursor string`	A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See the Pagination guide for more information.
`sort_field string`	Indicates how Customers should be sorted. Default: `DEFAULT`.
`sort_order string`	Indicates whether Customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. Default: `ASC`.

Response Fields

Name	Description
`errors Error [ ]`	Any errors that occurred during the request.
`customers Customer [ ]`	An array of `Customer` objects that match the provided query.
`cursor string`	A pagination cursor to retrieve the next set of results for the original query. Only present if the request succeeded and additional results are available. See the Pagination guide for more information.

Examples

curl https://connect.squareup.com/v2/customers \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

{
  "customers": [
    {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2016-03-23T20:21:54.859Z",
      "updated_at": "2016-03-23T20:21:55Z",
      "given_name": "Amelia",
      "family_name": "Earhart",
      "email_address": "Amelia.Earhart@example.com",
      "address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "10003",
        "country": "US"
      },
      "phone_number": "1-212-555-4240",
      "reference_id": "YOUR_REFERENCE_ID",
      "note": "a customer",
      "groups": [
        {
          "id": "545AXB44B4XXWMVQ4W8SBT3HHF",
          "name": "Aviation Enthusiasts"
        },
        {
          "id": "1KB9JE5EGJXCW.REACHABLE",
          "name": "Reachable"
        }
      ],
      "group_ids": [
        "545AXB44B4XXWMVQ4W8SBT3HHF"
      ],
      "segment_ids": [
        "1KB9JE5EGJXCW.REACHABLE"
      ]
    }
  ]
}

Customers API You are viewing an old version of the API 2020-11-18 Version 2020-11-18 All Versions Customers API List customers

Query Parameters

Response Fields

Examples

Share Feedback

You are viewing an old version of the API

All Versions

List customers