• 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.

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

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: 2020-11-18' \
  -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",
      "groups": [
        {
          "id": "545AXB44B4XXWMVQ4W8SBT3HHF",
          "name": "Aviation Enthusiasts"
        },
        {
          "id": "1KB9JE5EGJXCW.REACHABLE",
          "name": "Reachable"
        }
      ],
      "group_ids": [
        "545AXB44B4XXWMVQ4W8SBT3HHF"
      ],
      "segment_ids": [
        "1KB9JE5EGJXCW.REACHABLE"
      ]
    }
  ]
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?