Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Customer Segment API

Use the Customer Segments API

With the Customer Segments API, you can do the following:

Requirements and limitations
Permalink Get a link to this section

  • You must have CUSTOMERS_READ permissions to list and retrieve customers segments.

  • You cannot use the Customer Segments API to create customer segments. You must use the Square Seller Dashboard or a Square point-of-sale app to do so.

  • You cannot search for customers based on customer segment membership.

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

Retrieve segment membership information for a customer
Permalink Get a link to this section

When inspecting the customers returned in the customer search query , you come across a customer that also belongs to a customer segment, as indicated by the presence of a customer segment ID in the Customer's segment_ids field, assuming that the customer segment ID is "gv2:KF92J19VXN5FK30GX2E8HSGQ20". You can take that segment ID and retrieve the segment calling the Retrieve customer segment endpoint of the Customer Segments API as follows:

curl https://connect.squareup.com/v2/customers/segments/gv2:KF92J19VXN5FK30GX2E8HSGQ20 \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

In the response, you see that this customer segment is named "Loyal Customers", indicating that the customer meets the filter criteria defined for this segment.

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