Learn more about managing and using the Square Customer Groups API.
Customer Groups API

Manage Customers by Groups

A Customer group (also called a manual group) is an arbitrarily named collection of customers. 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 2020" and add customers to the group after they check in at a conference.

To learn more about customer groups, see Manage Customer Groups and Filters.

When retrieving a customer resource, you can determine the customer groups to which a given customer belongs using the following field on the customer resource:

  • group_ids. Lists all the customer groups to which the customer belongs.

Using the Customer Groups API with the Customers API allows developers to do CRUD management of customer groups, add and remove customers from customer groups, and search for customers based on membership. Developers can use the APIs to perform full lifecycle management and analysis of customer groups, and, in turn, automate and personalize customer interactions.

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 is not 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

  • 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 are not 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

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

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.