The Customers API provides the RetrieveCustomer, ListCustomers, and SearchCustomers endpoints that developers can use to find and view detailed information about customer profiles stored in a Square seller account. This topic describes how to call RetrieveCustomer to retrieve a specific customer profile and ListCustomers to list the customer profiles in the seller account.
To retrieve or list customer profiles, the seller account must have at least one customer profile. For information about how to create customer profiles using the Customers API, see Manage Customer Profiles.
Note
The RetrieveCustomer and ListCustomers endpoints cannot be used to retrieve custom attributes for customer profiles. However, you can use 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.
The RetrieveCustomer endpoint lets you get and view the details of a customer profile of a given ID. For example:
Retrieve customer
If successful, the operation returns a 200 response containing a single customer profile of the specified ID, as shown in the following response payload example:
{
"customer": {
"id": "TNQC0TYTWMRSFFQ157KK4V7MVR",
"created_at": "2020-04-27T17:28:50.073Z",
"updated_at": "2020-05-27T04:43:53Z",
"given_name": "John",
"family_name": "Doe",
"company_name": "Company",
"email_address": "[email protected]",
"address": {
"address_line_1": "123 Main Street",
"locality": "City",
"postal_code": "12345",
"country": "US"
},
"phone_number": "+12065551212",
"birthday": "0000-01-13",
"preferences": {
"email_unsubscribed": false
},
"creation_source": "THIRD_PARTY",
"segment_ids": [
"499XKDADA7682.REACHABLE"
],
"version": 0
}
}If the customer profile doesn't exist in the directory, the Customers API returns a 404 NOT_FOUND error.
Call ListCustomers to list the customer profiles in the Customer Directory of a Square seller.
List customers
If successful, the operation 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 response.
You can 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
This example also sets the optional count parameter to true, which directs Square to also return a count field that contains the total number of customer profiles in the directory. Only customer profiles that contain public information are counted.
The following is an excerpt of an example paged response:
{
"customers": [
{
// customer 1 fields
},
{
// customer 2 fields
},
{
// customer 3 fields
}
],
"cursor": "PNEhVUKBuTOuRIZoUcX5VQ...UE1cVyWmbXhoY",
"count": 13293
}Note
Square treats the limit value as advisory and might return more or fewer results.
When the number of results exceeds the page size, the response includes a cursor field. To get the next page of results, send your ListCustomers request and include the cursor, as shown in the following example:
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.
Did you know?
Although the ListCustomers endpoint can be used to retrieve all customers in the Customer Directory, it might not be practical to use the endpoint 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.