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 permission 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 application 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 segment_ids field, assuming that the customer segment ID is "gv2:KF92J19VXN5FK30GX2E8HSGQ20". You can take that segment ID and retrieve the segment calling the RetrieveCustomerSegment endpoint of the Customer Segments API as follows:

Retrieve Customer Segment
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/customers/segments/gv2%3AKF92J19VXN5FK30GX2E8HSGQ20 \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

In the following 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"
  }
}