Code Cookbook

Search for Customer Profiles

Retrieve a specific customer profile or search through customer profiles using specific queries.

Server Side
Client Side
Languages Supported

You can search through your customer profiles using specific queries or you can retrieve specific customer profiles using their customer_id.

Before you start

Search for customer profiles

Filtering for customer searches is currently limited to creation source and timestamps for creation and last update.

To search for customers:

  1. Create a new customer filter object and set the filter criteria. The code below uses a creation source filter that includes customer profiles in the result if they were created through the Square Point of Sale app or the Connect API.
// Define the filter criteria.
$filterBy = new \SquareConnect\Model\CustomerFilter;
$profileSources = array(

// Search for Customer profiles created through the Connect API
$creationSourceFilter = new \SquareConnect\Model\CustomerCreationSourceFilter;

  1. Define the sorting criteria. The code below uses default sorting (by given_name and family_name) in ascending order.
// Sort the results in ascending order by their creation timestamp
$sortBy = new \SquareConnect\Model\CustomerSort;

$customerQuery = new \SquareConnect\Model\CustomerQuery;
  1. Use the filter and sorting criteria to build a new CustomerQuery:
$customerQuery = new \SquareConnect\Model\CustomerQuery;
  1. Create a SearchCustomers request, set the query and advisory limit, and call SearchCustomers. The code below prints the result to the screen:
// Create a new request object for SearchCustomers.
$body = new \SquareConnect\Model\SearchCustomersRequest();

// Set an advisory limit on the number of results returned in a single page.

try {
    $result = $customersApi->searchCustomers($body);
} catch (Exception $e) {
    echo 'Exception when calling CustomersApi->searchCustomers: ',

Retrieve a specific customer profile

If you know the customer_id of the profile you need, you can use it to retrieve that specific customer profile.

  1. Set the customer_id of the customer you want to retrieve.
// The ID of the customer to update.
$customerId = '{REPLACE_ME}';
  1. Send your request to the RetrieveCustomer endpoint. For now, we'll print the raw result to the screen.
try {
    $result = $customersApi->retrieveCustomer($customerId);
} catch (Exception $e) {
    echo 'Exception when calling retrieveCustomer: ',

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow