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 permission to list and retrieve customer groups or to search for customers based on customer group membership.

  • You must have CUSTOMERS_WRITE permission 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 CreateCustomerGroup endpoint of the Customer Groups API as follows:

Create Customer Group
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareup.com/v2/customers/groups \
  -X POST \
  -H 'Square-Version: 2021-07-21' \
  -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 (POS)application. Similarly, you can add and remove customers to and from this customer group using the Customers API.

Manage customer group membership 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 AddGroupToCustomer endpoint of the Customers API as follows:

Add Group To Customer
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/customers/JDKYHBWT1D4F8MFH63DBMEN8Y4/groups/2TAT3CMH4Q0A9M87XJZED0WMR3 \
  -X PUT \
  -H 'Square-Version: 2021-07-21' \
  -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.

To remove a customer from a customer group, call the RemoveGroupFromCustomer endpoint of the Customers API. The following example removes the same customer from the group:

Remove Group From Customer
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/customers/JDKYHBWT1D4F8MFH63DBMEN8Y4/groups/2TAT3CMH4Q0A9M87XJZED0WMR3 \
  -X DELETE \
  -H 'Square-Version: 2021-07-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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 SearchCustomers endpoint of the Customers API to search for customers belonging to this group identified by its ID (2TAT3CMH4Q0A9M87XJZED0WMR3):

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareupsandbox.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2021-07-21' \
  -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.