Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Customers

  • List customers

  • Create customer

  • Bulk create customers

  • Bulk delete customers

  • Bulk retrieve customers

  • Bulk update customers

  • Search customers

  • Delete customer

  • Retrieve customer

  • Update customer

  • Remove group from customer

  • Add group to customer

  • Webhooks

  • customer.created

  • customer.deleted

  • customer.updated

<- Customers API

Customers 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

List customer profiles

Try in API Explorer
Link to section

Query parameters

Example code

Link to section

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.

Link to section

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.

Link to section

sort_field

string

Indicates how customers should be sorted.

The default value is DEFAULT.

Link to section

sort_order

string

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

The default value is ASC.

Link to section

count

boolean

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

The default value is false.

Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

customers

The customer profiles associated with the Square account or an empty object ({}) if none are found. Only customer profiles with public information (given_name, family_name, company_name, email_address, or phone_number) are included in the response.

Link to section

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.

Link to section

count

integer(64-bit)

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.

Link to section

Examples

All versions ->

GET /v2/customers
curl https://connect.squareup.com/v2/customers \ -H 'Square-Version: 2026-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": "[email protected]", "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 } ] }