Customers API Search endpoint returns empty object when filtering by group_id

I’m having a problem with the Search endpoint on the Customers API when filtering by group_id. The following request returns a 200 response and an empty object. I’m using the Square API Explorer to test this. The Customer API search endpoint successfully returns results on a search with no query filters. I’m certain that the group_id is valid because I obtained it from one such search. I’ve also tried several other group_ids with no luck.

I’ve replaced my access token with “MY_TOKEN” in this example, but am using the correct token in my actual search. Any ideas what I’m missing?

curl \
  -X POST \
  -H 'Square-Version: 2020-12-16' \
  -H 'Authorization: Bearer MY_TOKEN \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "group_ids": {
          "all": [

“REACHABLE” is a segment, not a group, as far as I know. If you use ListSegments you should find it, but there’s currently not a way to search by segment_id.

Thanks @sjosey. I see that this is a segment_id, but it also shows up under group_ids for that customer, as do seemingly all other segments in the system. I’m not totally clear on how segments are created. I’d like this segment to be searchable as a group. Is it possible to convert this to a group somehow in the dashboard?

Segments are dynamically created by Square, not by the merchant/developer. There’s no way to convert it to a group as of right now, though.

Thanks @sjosey. I guess I’m confused why this id shows up under both “segment_ids” and “group_ids” for this customer if it’s not a group id. Is there a reason for this?

Sorry I missed that. Where are you seeing them show up under both? When I call ListCustomers, I see group_ids and segment_ids showing separately. They do both admittedly show up under the groups, which I think was an older field before the group/segment APIs were released, so they’re not separated there.

Here’s an example. The same id appears under group and segments.

      "created_at": "2019-06-17T00:31:51.109Z",
      "updated_at": "2020-01-12T22:52:29Z",
      "given_name": "name",
      "family_name": "name",
      "preferences": {
        "email_unsubscribed": false
      "groups": [
          "id": "gv2:C4XRPFXTYD1X8NQX1GDXK57754",
          "name": "Instant Profile"
      "creation_source": "INSTANT_PROFILE",
      "segment_ids": [

Right, as mentioned above the groups is an older field that shows both groups and segments. If a customer actually belongs to groups and segments, there would be an additional field called group_ids. This customer only has segments, though. I can definitely share with the team though to see if maybe we can remove this field to reduce confusion.

1 Like

Ah ha, got it. Many thanks for the explanation!

1 Like