List Customers

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

Query

Query

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
  }
}

{
  "filter": {
    "hasActiveSubscription": { "is": true }
  },
  "paging": {
    "first": 20
  },
  "sorting": [
    { "field": "createdAt", "direction": "DESC" }
  ]
}

{
  "data": {
    "customers": {
      "edges": [
        {
          "node": {
            "customerId": "customer-123",
            "name": "Acme Corp",
            "email": "[e-mail]",
            "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
    }
  }
}

Parameters

filter · CustomerFilter

Filter criteria for customers

Show properties

customerId · StringFieldComparison

Filter by customer ID (eq, in, like, etc.)

name · StringFieldComparison

Filter by customer name

email · StringFieldComparison

Filter by email address

billingId · StringFieldComparison

Filter by billing provider ID

createdAt · DateFieldComparison

Filter by creation date

searchQuery · CustomerSearchQueryFilterComparison

Full-text search across customer fields

subscriptions · CustomerFilterCustomerSubscriptionFilter

Filter by subscription properties

and · [CustomerFilter]

Combine multiple filters with AND logic

or · [CustomerFilter]

Combine multiple filters with OR logic

paging · CursorPaging

Pagination options

Show properties

first · Int

Number of items to fetch (forward pagination)

after · String

Cursor to fetch items after

last · Int

Number of items to fetch (backward pagination)

before · String

Cursor to fetch items before

sorting · [CustomerSort]

Sorting options

Show properties

field · CustomerSortFields · required

Field to sort by: createdAt, updatedAt, customerId, name, email

direction · SortDirection · required

Sort direction: ASC or DESC

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

{
  "filter": {
    "email": { "like": "[e-mail]" }
  }
}

Find customers created this month

{
  "filter": {
    "createdAt": { "gte": "2024-01-01T00:00:00Z" }
  }
}

Find customers with specific subscription status

{
  "filter": {
    "subscriptions": {
      "status": { "eq": "ACTIVE" }
    }
  }
}

Full-text search

{
  "filter": {
    "searchQuery": { "like": "acme" }
  }
}

Common Use Cases

Admin dashboard

Display paginated list of customers with search and filtering capabilities.

Export customers

Iterate through all customers using pagination for data export.

Find customers by plan

Filter customers subscribed to a specific plan.

Related Operations

• Get Customer - Get single customer by ID
• Provision Customer - Create new customer