> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Customers

Retrieves a paginated list of customers with optional filtering and sorting.

## Query

<CodeGroup>
  ```graphql Query theme={null}
  query ListCustomers(
    $filter: CustomerFilter
    $paging: CursorPaging
    $sorting: [CustomerSort!]
  ) {
    customers(filter: $filter, paging: $paging, sorting: $sorting) {
      edges {
        node {
          customerId
          name
          email
          hasActiveSubscription
          createdAt
          subscriptions {
            subscriptionId
            status
            plan {
              refId
            }
          }
        }
        cursor
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
    }
  }
  ```

  ```json Variables theme={null}
  {
    "filter": {
      "hasActiveSubscription": { "is": true }
    },
    "paging": {
      "first": 20
    },
    "sorting": [
      { "field": "createdAt", "direction": "DESC" }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "customers": {
        "edges": [
          {
            "node": {
              "customerId": "customer-123",
              "name": "Acme Corp",
              "email": "billing@acme.com",
              "hasActiveSubscription": true,
              "createdAt": "2024-01-15T10:30:00Z",
              "subscriptions": [
                {
                  "subscriptionId": "sub-456",
                  "status": "ACTIVE",
                  "plan": {
                    "refId": "plan-pro"
                  }
                }
              ]
            },
            "cursor": "abc123"
          }
        ],
        "pageInfo": {
          "hasNextPage": true,
          "hasPreviousPage": false,
          "startCursor": "abc123",
          "endCursor": "xyz789"
        },
        "totalCount": 150
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="filter" type="CustomerFilter">
  Filter criteria for customers

  <Expandable title="properties">
    <ParamField body="customerId" type="StringFieldComparison">
      Filter by customer ID (eq, in, like, etc.)
    </ParamField>

    <ParamField body="name" type="StringFieldComparison">
      Filter by customer name
    </ParamField>

    <ParamField body="email" type="StringFieldComparison">
      Filter by email address
    </ParamField>

    <ParamField body="billingId" type="StringFieldComparison">
      Filter by billing provider ID
    </ParamField>

    <ParamField body="createdAt" type="DateFieldComparison">
      Filter by creation date
    </ParamField>

    <ParamField body="searchQuery" type="CustomerSearchQueryFilterComparison">
      Full-text search across customer fields
    </ParamField>

    <ParamField body="subscriptions" type="CustomerFilterCustomerSubscriptionFilter">
      Filter by subscription properties
    </ParamField>

    <ParamField body="and" type="[CustomerFilter]">
      Combine multiple filters with AND logic
    </ParamField>

    <ParamField body="or" type="[CustomerFilter]">
      Combine multiple filters with OR logic
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="paging" type="CursorPaging">
  Pagination options

  <Expandable title="properties">
    <ParamField body="first" type="Int">
      Number of items to fetch (forward pagination)
    </ParamField>

    <ParamField body="after" type="String">
      Cursor to fetch items after
    </ParamField>

    <ParamField body="last" type="Int">
      Number of items to fetch (backward pagination)
    </ParamField>

    <ParamField body="before" type="String">
      Cursor to fetch items before
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sorting" type="[CustomerSort]">
  Sorting options

  <Expandable title="properties">
    <ParamField body="field" type="CustomerSortFields" required>
      Field to sort by: `createdAt`, `updatedAt`, `customerId`, `name`, `email`
    </ParamField>

    <ParamField body="direction" type="SortDirection" required>
      Sort direction: `ASC` or `DESC`
    </ParamField>
  </Expandable>
</ParamField>

## Return Type

Returns a `CustomerConnection` with:

| Field          | Type            | Description                        |
| -------------- | --------------- | ---------------------------------- |
| `edges`        | \[CustomerEdge] | List of customer edges             |
| `edges.node`   | Customer        | The customer object                |
| `edges.cursor` | String          | Cursor for pagination              |
| `pageInfo`     | PageInfo        | Pagination metadata                |
| `totalCount`   | Int             | Total number of matching customers |

## Filter Examples

### Find customers by email domain

```json theme={null}
{
  "filter": {
    "email": { "like": "%@acme.com" }
  }
}
```

### Find customers created this month

```json theme={null}
{
  "filter": {
    "createdAt": { "gte": "2024-01-01T00:00:00Z" }
  }
}
```

### Find customers with specific subscription status

```json theme={null}
{
  "filter": {
    "subscriptions": {
      "status": { "eq": "ACTIVE" }
    }
  }
}
```

### Full-text search

```json theme={null}
{
  "filter": {
    "searchQuery": { "like": "acme" }
  }
}
```

## Common Use Cases

<AccordionGroup>
  <Accordion title="Admin dashboard">
    Display paginated list of customers with search and filtering capabilities.
  </Accordion>

  <Accordion title="Export customers">
    Iterate through all customers using pagination for data export.
  </Accordion>

  <Accordion title="Find customers by plan">
    Filter customers subscribed to a specific plan.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Get Customer](/api-and-sdks/api-reference/queries/get-customer) - Get single customer by ID
* [Provision Customer](/api-and-sdks/api-reference/mutations/provision-customer) - Create new customer