Customer Groups API Overview

A customer group (also called a manual group) is an arbitrarily named collection of customers. Customer groups can be used to organize customers and enable personalized customer experiences at scale. Sellers and developers have full control over the definition, management, and customer membership of these groups. For example, a seller can create a customer group called "Summer Conference 2022" and add customers to the group as they check in at the conference. For more information about this example scenario, see Use the Customer Groups API.

You can use the Customer Groups API with the Customers API to create and manage customer groups that enable targeted promotions and customized actions based on group membership.

The Customer Groups API lets you create or update a customer group by providing a name, retrieve metadata about groups, and delete a group. The following is an example of a customer group:

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

The Customers API lets you add a customer to a group, remove a customer from a group, and search for customers based on membership in particular customer groups. If a customer belongs to one or more customer groups, the corresponding customer profile includes a group_ids field that lists the IDs of the groups to which the customer belongs. This excerpt of a customer profile shows that the customer currently belongs to two groups:

{
  "customer": 
  {
    "id": "RAWCQZA0D0YRSD2MEC687KC79W",
    "created_at": "2020-04-22T20:52:06.070Z",
    "updated_at": "2022-05-29T18:55:36Z",
    ...
    "group_ids": [
      "2TAT3CMH4Q0A9M87XJZED0WMR3",
      "GHW0ZG7WAFS5JYJAEKBMZRCAN"
    ],
    "version": 15
  }
}

Using the Customer Groups API and Customers API to perform full lifecycle management and analysis of customer groups can help inform ways to automate and personalize customer interactions. You can then integrate with other Square APIs to provide robust experiences for sellers and their customers.

The following migration notes apply to the Customer Groups API.

Starting in version: 2022-03-16

Calls to the CreateCustomerGroup or UpdateCustomerGroup endpoint that contain an unrecognized field now return a BAD_REQUEST error. An unrecognized field is any field in the request body that isn't supported for the request. For earlier Square versions, the Customer Groups API continues to ignore unrecognized fields.

The following are example responses based on the Square version:

• Square version 2022-03-16 and later: 400 BAD_REQUEST

  {
    "errors": [
      {
        "code": "BAD_REQUEST",
        "detail": "The field named '{field_name}' is unrecognized (line 4, character 9)",
        "field": "{field_name}",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }

• Square version 2022-02-16 and earlier: 200 OK (unrecognized fields are ignored)

Starting in version: 2022-03-16

Calls to the CreateCustomerGroup endpoint for the same seller account that reuse an idempotency key from a previous CreateCustomerGroup request aren't processed, even if a different name is specified. For these requests, Square now returns the response from the original request processed using the idempotency key. For earlier Square versions, the Customer Groups API continues to return an INVALID_VALUE error.

The following are example responses based on the Square version:

• Square version 2022-03-16 and later: 200 OK

  {
    "group": {                      // Group object from the original request
      "id": "7WDV991WCZD7BW4896CZYGAEAS", 
      "name": "Dog lovers", 
      "created_at": "2022-02-16T20:53:33.175Z",
      "updated_at": "2022-02-16T20:53:33"
    }
  }

• Square version 2022-02-16 and earlier: 400 INVALID_VALUE

  {
    "errors": [
      {
        "code": "INVALID_VALUE",
        "detail": "name",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }

• Use the Customer Groups API
• Customers API Overview
• API Reference: Customer Groups API
• API Reference: Customers API