Use the Customer Groups API

Applies to: Customer Groups API | Customers API

Learn how to use the Square Customer Groups API to organize customer profiles.

Together with the Customers API, the Customer Groups API lets you create and manage customer groups to organize customer profiles in a Square seller account.

The following sections walks you through some basic tasks for using the APIs. As an example scenario, you create a customer group named "Summer Conference 2022", add conference attendees to the group, and then search for attendees so that you can analyze related data.

• You must have CUSTOMERS_READ permission to retrieve customers and customer groups or search for customers based on customer group membership.
• You must have CUSTOMERS_WRITE permission to create, update, or delete customer groups and to add customers to or remove customers from customer groups.
• You must use Square Version 2020-04-22 or later to call the Customer Groups API.

To create the new customer group, call CreateCustomerGroup in the Customer Groups API and provide the name of the group:

If the request is successful, Square returns the new customer group in the response:

{
  "group": {
    "id": "2TAT3CMH4Q0A9M87XJZED0WMR3",
    "name": "Summer Conference 2022",
    "created_at": "2022-04-22T21:54:57.863Z",
    "updated_at": "2022-04-22T21:54:58Z"
  }
}

You can now retrieve, update, or delete this customer group using the Customer Groups API, as well as in the Square Dashboard and Square Point of Sale application.

After the customer group is created, you use the AddGroupToCustomer and RemoveGroupFromCustomer endpoints in the Customers API to manage group membership for customer profiles.

Continuing with the Summer Conference 2022 scenario, suppose you want to integrate with the conference registration system. As each attendee checks in for the conference, you find or create a corresponding customer profile, as follows:

• First, call SearchCustomers in the Customers API to search for a customer profile by phone number, email address, or other supported query filter.
• If a matching customer profile cannot be found, call CreateCustomer in the Customers API to create a new one.

After you find or create the customer profile, call AddGroupToCustomer to add the group membership to the profile. To do so, provide the ID of the customer profile and the ID of the customer group.

If the request is successful, Square returns a 200 status code with an empty object:

{}

Square also adds the group ID to the group_ids field of the customer profile. If you want to get the IDs of all groups that a customer profile belongs to, call RetrieveCustomer in the Customers API and check the group_ids field. The following example customer profile has one group membership:

{
  "customer": {
    "id": "A9641GZW2H7Z56YYSD41Q12HDW",
    "created_at": "2020-09-21T22:59:16.271Z",
    "updated_at": "2022-04-22T23:12:47Z",
    "given_name": "Joan",
    "family_name": "Doe",
    "company_name": "ACME Inc",
    "email_address": "[email protected]",
    "phone_number": "14065551112",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "group_ids": [
      "2TAT3CMH4Q0A9M87XJZED0WMR3"
    ],
    "segment_ids": [
      "KTDR6CEPCW57S.REACHABLE"
    ],
    "version": 4
  }
}

To remove a group membership from a customer profile, call RemoveGroupFromCustomer using the ID of the customer profile and the ID of the customer group:

If the request is successful, Square returns a 200 status code with an empty object:

{}

Square also removes the group ID from the group_ids field of the customer profile. Note that group_ids field is present only if the customer profile belongs to one or more customer groups.

When the conference ends, you want to quickly retrieve the list of customers who attended the conference and analyze the data for customer orders or payments. To do so, call SearchCustomers to search for customers belonging to the group, which is identified by its ID.

The group_ids filter in the previous example uses the all field to specify that the returned customer profiles must belong to all specified groups. In this example, the all list contains a single entry that represents the "Summer Conference 2022" group.

You can then analyze and export the returned customer data collected for these customers, such as email addresses and phone numbers. You can also cross-reference the customer IDs in other Square APIs (such as the Orders API) to identify and analyze purchase behavior by these customers.

You can call ListCustomerGroups in the Customer Groups API to retrieve the customer groups for a business. The following example uses the optional limit query parameter to specify a maximum page size of three results. The default page size is 50.

If successful, the operation returns a 200 response that contains a list of customer groups or an empty object ({}) if no groups exist. The following is an excerpt of an example paged response:

{
  "groups": [
    {
      "id": "GHW0ZG7WAFS5ZYJAEKBMJRCAN",
      ...
    },
    {
      "id": "3XC8C32TMDEBMXBYQ4NHD18C0E",
      ...
    },
    {
      "id": "2TAT3CMH4Q0A9M87XJZED0WMR3",
      ...
    }
  ],
  "cursor": "PNEhVUKBuTOuRIZoUcX5VQ...UE1cVyWmbXhoY"
}

When the number of results exceeds the page size, the response includes a cursor field. To get the next page of results, add the cursor to your next ListCustomerGroups request, as shown in the following example:

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