Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Customer Groups API

Use the Customer Groups API

Together with the Customers API, the Customer Groups API lets you create and manage customer groups to organize customer profiles in a Square seller's account. The following discussion walks you through some basic tasks for using the APIs.

Requirements and limitations
Permalink Get a link to this section

  • You must have CUSTOMERS_READ permissions to list and retrieve customer groups, or to search for customers based on customer group membership.

  • You must have CUSTOMERS_WRITE permissions to create, update, or delete customer groups as well as to add customers to and remove customers from customer groups.

  • You must use Square Version “2020-04-22” or later to call the Customer Groups API.

Create a customer group
Permalink Get a link to this section

As an example, create a customer group named "Summer Conference 2020", add customers that attend the conference to this group, and then search for and analyze data about those customers.

To create the new customer group, call the Create Customer Group endpoint of the Customer Groups API as follows:

curl https://connect.squareup.com/v2/customers/groups \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "group": {
      "name": "Summer Conference 2020"
    }
  }'

In the response, you receive the created customer group:

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

You can now retrieve and modify this customer group with the Customer Groups API, as well as in the Square Seller Dashboard and a Square point-of-sale app. Similarly, you can also add and remove customers to and from this customer group using the Customers API.

Add customers to a customer group
Permalink Get a link to this section

Imagine you want to integrate with the conference registration system. As customers check in for the conference, you use the Customers API to search for and identify the customer (or create a new customer) for each registrant. After you identify (or create) each customer using the Customers API, you can add each customer as identified by its customer_id (for example, JDKYHBWT1D4F8MFH63DBMEN8Y4) to the created group (in this case, "Summer Conference 2020"). To do so, call the Add Group to Customer endpoint of the Customers API as follows:

curl https://connect.squareup.com/v2/customers/JDKYHBWT1D4F8MFH63DBMEN8Y4
/groups/2TAT3CMH4Q0A9M87XJZED0WMR3 \
  -X PUT \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The request is successful if the response returns a 200 status code with an empty body.

Note that the first ID path after customers is the ID (JDKYHBWT1D4F8MFH63DBMEN8Y4) of the customer to add to the group, and the second ID path after groups is the ID (2TAT3CMH4Q0A9M87XJZED0WMR3) of the group.

Search for customers based customer group membership
Permalink Get a link to this section

When the conference ends, you want to quickly retrieve the list of customers that attended the conference and analyze the data for customer orders or payments. To accomplish this, call the Search customers endpoint of the Customers API to search for customers belonging to this group identified by its ID (2TAT3CMH4Q0A9M87XJZED0WMR3):

curl   https://connect.squareup.com/v2/customers/search \
  -X POST \
-X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
        "filter": {
          "group_ids": {
               "all":  ["2TAT3CMH4Q0A9M87XJZED0WMR3"]
          }
        }
    }
}'

This group_ids filter specifies that selected customer profiles must belong to every group listed in the all list. In this case, the list just contains a single entry, 2TAT3CMH4Q0A9M87XJZED0WMR3, for the "Summer Conference 2020" group.

You can then analyze and export the returned customer data (such as email addresses and phone numbers) collected for these customers. 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.