• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
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 cursor to retrieve the next set of results for your original query.

For more information, see Pagination.
limit
integer (32-bit)

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
string

Indicates how customers should be sorted.

The default value is DEFAULT.
sort_order
string

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

The default value is ASC.

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
customers
Customer [ ]

The customer profiles associated with the Square account or an empty object ({}) if none are found.
cursor
string

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.

Examples

You are viewing an old version of the API
GET /v2/customers
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/customers \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
Response 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",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "THIRD_PARTY",
      "group_ids": [
        "545AXB44B4XXWMVQ4W8SBT3HHF"
      ],
      "segment_ids": [
        "1KB9JE5EGJXCW.REACHABLE"
      ],
      "version": 1
    }
  ]
}