Retrieve Customer Profiles

Developers can use the following endpoints in the Customers API to get detailed information about customer profiles stored in a seller's Customer Directory:


The SearchCustomers endpoint in the Customers API can be used to find and view customer profiles based on phone number, email address, or other query filters. For more information, see Search for Customer Profiles.

Several list and search endpoints in other Square APIs return objects that are associated with a customer, such as orders, bookings, cards on file, and custom attributes. For more information, see Customer ID integration points.

To get details about a single customer profile, call RetrieveCustomer and provide the customer ID, as shown in the following request:

Retrieve customer


The BulkRetrieveCustomers endpoint can also be used to retrieve a single customer.

If the RetrieveCustomer operation is successful, Square returns a 200 status code and a customer field that contains the requested customer profile. For example:

To retrieve 1 to 100 customer profiles in a bulk operation, call BulkRetrieveCustomers and provide a list of customer IDs.

The following BulkRetrieveCustomers request retrieves three customer profiles:

Bulk retrieve customers

For bulk operations, Square processes the retrieved requests individually and returns a map of responses.

If the BulkRetrieveCustomers operation is successfully processed, Square returns a 200 status code and a responses map of key-value pairs that represent the responses for individual retrieve requests.

For each key-value pair, the key is a customer ID that was specified in the request and the value is either the requested customer profile (if the request succeeded) or error information (if the request failed). For example:

Note that the responses might not be returned in the same order as the list of customer IDs sent to BulkRetrieveCustomers.

To list the customer profiles in the seller's Customer Directory, call ListCustomers.

List customers

If the ListCustomers operation is successfully processed, Square returns returns a 200 response that contains a list of customer profiles or an empty object ({}) if no profiles exist.

Only customer profiles that contain public information (given_name, family_name, company_name, email_address, or phone_number) are included in the results. Customer profiles with no public information are excluded.

Link to section

Sorting the results

By default, Square sorts the results by concatenating the given_name and family_name fields of each customer profile and returning them in ascending order. If neither field is set, a string comparison is performed using one of the following fields in the following order: company_name, email_address, phone_number.

You can optionally use the sort_field query parameter to sort by the created_at field and the sort_order query parameter to sort by descending order.

List customers

Link to section

Setting a page size

You can also optionally specify a maximum page size in the request. The following example request uses the limit query parameter to specify a maximum page size of three results. The default page size is 100.

List customers


Square treats the limit value as advisory and might return more or fewer results.

The following is an excerpt of an example paged response with the count field:

{ "customers": [ { // customer 1 fields }, { // customer 2 fields }, { // customer 3 fields } ], "cursor": "PNEhVUKBuTOuRIZoUcX5VQ...UE1cVyWmbXhoY", "count": 13293 }

When the number of results exceeds the page size, the response includes a cursor field. To get the next page of results, send the previous ListCustomers request and include the cursor query parameter set to the cursor returned in the response.

List customers

To retrieve all customer profiles, use the new cursor value returned in each response for the next request, until the response doesn't include a cursor field.

Link to section

Getting the customer count

The preceding example also sets the optional count parameter to true, which directs Square to return a count field that contains the total number of customer profiles in the directory.

Only customer profiles that contain public information (given_name, family_name, company_name, email_address, or phone_number) are included in the count. Customer profiles with no public information are excluded.

Link to section


  • Use SearchCustomers with a large customer base - Although the ListCustomers endpoint can be used to retrieve all customers in the Customer Directory, it might not be practical with a large customer base. Using the SearchCustomers endpoint with one or more query filters is a more efficient method for retrieving customers when you don't know their IDs. For more information, see Search for Customer Profiles.

  • Synchronizing customer data - To synchronize customer data from the Customer Directory to your application, you can use customer webhooks to be notified of changes in addition to polling periodically with the SearchCustomers or ListCustomers endpoint.

  • Custom attributes not included in Customer API responses - The RetrieveCustomer, BulkRetrieveCustomers, and ListCustomers endpoints cannot be used to retrieve custom attributes for customer profiles. However, you can use the customer ID with the RetrieveCustomerCustomAttribute or ListCustomerCustomAttributes endpoint to retrieve or list custom attributes for a specified customer profile, including seller-defined custom fields. For more information, see Create and Manage Customer Custom Attributes.

  • Customer profiles have multiple sources - Customer profiles returned in RetrieveCustomer, BulkRetrieveCustomers, and ListCustomers responses include customers created using the Seller Dashboard, Square Point of Sale, the Customers API, and other flows. For example, a customer profile might be created for loyalty accounts and instant profiles might be created for payments. For information about how to create customer profiles using the Customers API, see Manage Customer Profiles.

    Sometimes Square creates instant profiles that have no public information. These instant profiles aren't included in ListCustomers or SearchCustomers responses.

Link to section

See also