# List the customers in a segment

> Page through the members of a customer segment with customerSegmentMembers, or run an ad hoc segment query with customerSegmentMembersQueryCreate.

Page: https://lintelagency.com/resources/graphql/customer-segment-members

## In short

To list the customers in a segment, query customerSegmentMembers with the segmentId and page with first and after; totalCount gives the size. To test a segment query without saving it, start customerSegmentMembersQueryCreate with a ShopifyQL condition such as number_of_orders >= 3, wait until done is true, then pass its ID as queryId to customerSegmentMembers. Both need read_customers.

## Facts

- **API:** Admin GraphQL API
- **Operations:** customerSegmentMembers, customerSegmentMembersQueryCreate, customerSegmentMembersQuery
- **Access scope:** read_customers
- **API version:** 2026-10
- **Last checked:** 2 November 2026

## How to use it

1. Find the segment ID with the segments query, which lists each segment’s name and query.
2. Send SegmentMembers with first: 100 and page with after: endCursor while hasNextPage is true.
3. For an unsaved condition, send StartMembersQuery, poll customerSegmentMembersQuery(id) until done, then query customerSegmentMembers(queryId: …).
4. Use the member IDs to tag customers, send codes or export to your email tool.

## Code

### segment-members.graphql

```graphql
query SegmentMembers($segmentId: ID!, $first: Int!, $after: String) {
  customerSegmentMembers(segmentId: $segmentId, first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        displayName
        numberOfOrders
        amountSpent {
          amount
          currencyCode
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

### segment-members.variables.json

```json
{
  "segmentId": "gid://shopify/Segment/1234567890",
  "first": 100,
  "after": null
}
```

### segment-members.response.json

```json
{
  "data": {
    "customerSegmentMembers": {
      "totalCount": 1842,
      "edges": [
        {
          "node": {
            "id": "gid://shopify/CustomerSegmentMember/1111111111",
            "displayName": "Ada Example",
            "numberOfOrders": "7",
            "amountSpent": {
              "amount": "642.50",
              "currencyCode": "EUR"
            }
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJsYXN0X2lkIjoxMTExMTExMTExfQ=="
      }
    }
  }
}
```

### members-query-create.graphql

```graphql
mutation StartMembersQuery($input: CustomerSegmentMembersQueryInput!) {
  customerSegmentMembersQueryCreate(input: $input) {
    customerSegmentMembersQuery {
      id
      done
      currentCount
    }
    userErrors {
      code
      field
      message
    }
  }
}
```

### members-query-create.variables.json

```json
{
  "input": {
    "query": "number_of_orders >= 3 AND email_subscription_status = 'SUBSCRIBED'"
  }
}
```

### members-query-create.response.json

```json
{
  "data": {
    "customerSegmentMembersQueryCreate": {
      "customerSegmentMembersQuery": {
        "id": "gid://shopify/CustomerSegmentMembersQuery/1234567890",
        "done": false,
        "currentCount": 0
      },
      "userErrors": []
    }
  }
}
```

## Limits and edge cases

- The connection has edges, not nodes: read edges[].node.
- Segment queries use Shopify’s segment query language, not the admin search syntax.
- Contact fields such as email and phone are protected customer data; request access before selecting them.
- numberOfOrders is an UnsignedInt64 and comes back as a string.

## Questions

### How do I export a Shopify customer segment with the API?

Page through customerSegmentMembers with the segment ID and write each member to your file or tool.

### Can I run a segment query without saving a segment?

Yes. customerSegmentMembersQueryCreate runs a condition asynchronously; pass its ID as queryId when it is done.

### Which scope do segment queries need?

read_customers. Writing segments with segmentCreate needs write_customers.

## Shopify documentation

- [customerSegmentMembers](https://shopify.dev/docs/api/admin-graphql/latest/queries/customerSegmentMembers)
- [Segment query language](https://shopify.dev/docs/api/shopifyql/segment-query-language-reference)

## Related

- [Add tags to orders, customers or products in bulk](https://lintelagency.com/resources/graphql/bulk-add-tags)
- [Add discount codes in bulk](https://lintelagency.com/resources/graphql/bulk-discount-codes)
- [Page through results with cursors](https://lintelagency.com/resources/graphql/cursor-pagination)

License: MIT. Free to use in your own store and in client work.