Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-143281,4552.1 MB
Customers

ListCustomers

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.

get/v2/customers

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 your original query.

For more information, see Pagination.

limitinteger

The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 100, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100.

For more information, see Pagination.

sort_field'DEFAULT' | 'CREATED_AT'

Specifies customer attributes as the sort key to customer profiles returned from a search.

Indicates how customers should be sorted.

The default value is DEFAULT.

sort_order'DESC' | 'ASC'

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

Indicates whether customers should be sorted in ascending (ASC) or descending (DESC) order.

The default value is ASC.

countboolean

Indicates whether to return the total count of customers in the count field of the response.

The default value is false.

Response

Success

cursorstring

A pagination cursor to retrieve the next set of results for the original query. A cursor is only present if the request succeeded and additional results are available.

For more information, see Pagination.

countinteger

The total count of customers associated with the Square account. Only customer profiles with public information (given_name, family_name, company_name, email_address, or phone_number) are counted. This field is present only if count is set to true in the request.

Example response

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