Use the Customer Segments API

With the Customer Segments API, you can get information about the customer segments that are defined by Square or a Square seller. Customer segments are also known as smart groups.

Link to section

Requirements and limitations

• You must have CUSTOMERS_READ permission to list and retrieve customer segments.

• You cannot use the Customer Segments API to create or update customer segments or to view filters that define a customer segment. Sellers create and manage segments in the Seller Dashboard or Square Point of Sale. For more information, see Manage Customer Groups and Filters.

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

Link to section

Retrieve segment information for a customer

When inspecting customers returned by SearchCustomers or another Customers API endpoint, you might find that a customer belongs to one or more customer segments. Segment membership is indicated by the presence of the segment_ids field in the Customer object, as shown in the following excerpt:

{
  "id": "RAWCQZA0D0YRSD2MEC687KC79W",
  "created_at": "2020-04-22T20:52:06.070Z",
  "updated_at": "2021-12-29T18:55:36Z",
  ...
  "segment_ids": [
    "8QJTJCE6AZSN6.REACHABLE",
    "8QJTJCE6AZSN6.CARDS_ON_FILE",
    "gv2:KF92J19VXN5FK30GX2E8HSGQ20"
  ],
  "version": 3
}

This customer currently belongs to three segments. To retrieve the name and other metadata for a segment, call RetrieveCustomerSegment and provide a segment ID, as shown in the following example:

curl https://connect.squareupsandbox.com/v2/customers/segments/{{SEGMENT_ID}} \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

This example response shows that the retrieved customer segment is named "Lunch regulars":

{
  "segment": {
    "id": "gv2:KF92J19VXN5FK30GX2E8HSGQ20",
    "name": "Lunch regulars",
    "created_at": "2020-01-09T19:33:24.469Z",
    "updated_at": "2020-04-13T23:01:13Z"
  }
}

Link to section

List customer segments

Call ListCustomerSegments to retrieve the customer segments for a business. The following example uses the optional limit query parameter to specify a maximum page size of three results. The default page size is 50.

curl https://connect.squareupsandbox.com/v2/customers/segments?limit=3 \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

If successful, the operation returns a 200 response that contains a list of customer segments. The following is an excerpt of an example paged response:

{
  "segments": [
    {
      "id": "gv2:KF92J19VXN5FK30GX2E8HSGQ20",
      ...
    },
    {
      "id": "8JJTQCE6AZSN6.CARDS_ON_FILE",
      ...
    },
    {
      "id": "8QJTJBE6AZGN6.REACHABLE",
      ...
    }
  ],
  "cursor": "PNEhVUKBuTOuRIZoUcX5VQ...UE1cVyWmbXhoY"
}

When the number of results exceeds the page size, the response includes a cursor field. To get the next page of results, add the cursor to your next ListCustomerSegments request, as shown in the following example:

curl https://connect.squareupsandbox.com/v2/customers/segments?limit=3&cursor=PNEhVUKBuTOuRIZoUcX5VQ...UE1cVyWmbXhoY \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

To retrieve all customer segments, use the new cursor value returned in each response for the next request, until the response doesn't include a cursor field.

Link to section

Search for customers based on segment membership

The SearchCustomers endpoint in the Customers API provides the segment_ids filter to search for customers based on the segments they belong to. With this filter, you can specify up to three segment IDs using the all, any, and none fields.

For more information, including example queries, see Search by segment IDs.