Use the Customer Segments API

Applies to: Customer Segments API | Customers API

Learn how to discover available segments in a business and retrieve a specific segment ID to inspect its details.

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.

• 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 Square 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.

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:

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"
  }
}

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.

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:

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.

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.