Applies to: Customer Groups API | Customers API | Catalog API
Learn about managing customer groups using the Customer Groups API.
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.
Note
Catalog pricing rules provide built-in integration with customer groups. The Catalog API supports creating discounts that are automatically applied to customers who belong to a customer group. For more information, see Create Customer Group Discounts.
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" } ] }