List Subscriptions

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

Query

Query

query ListSubscriptions(
  $filter: SubscriptionQueryFilter
  $paging: CursorPaging
  $sorting: [SubscriptionQuerySort!]
) {
  subscriptions(filter: $filter, paging: $paging, sorting: $sorting) {
    edges {
      node {
        subscriptionId
        status
        startDate
        currentBillingPeriodEnd
        plan {
          refId
          displayName
        }
        customer {
          customerId
          name
        }
        prices {
          billingPeriod
          price {
            amount
            currency
          }
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

{
  "filter": {
    "status": { "in": ["ACTIVE", "IN_TRIAL"] }
  },
  "paging": {
    "first": 20
  },
  "sorting": [
    { "field": "createdAt", "direction": "DESC" }
  ]
}

{
  "data": {
    "subscriptions": {
      "edges": [
        {
          "node": {
            "subscriptionId": "sub-456",
            "status": "ACTIVE",
            "startDate": "2024-01-15T00:00:00Z",
            "currentBillingPeriodEnd": "2024-02-15T00:00:00Z",
            "plan": {
              "refId": "plan-pro",
              "displayName": "Pro Plan"
            },
            "customer": {
              "customerId": "customer-123",
              "name": "Acme Corp"
            },
            "prices": [
              {
                "billingPeriod": "MONTHLY",
                "price": {
                  "amount": 99,
                  "currency": "USD"
                }
              }
            ]
          },
          "cursor": "abc123"
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "xyz789"
      },
      "totalCount": 250
    }
  }
}

Parameters

filter · SubscriptionQueryFilter

Filter criteria for subscriptions

Show properties

subscriptionId · StringFieldComparison

Filter by subscription ID

status · SubscriptionStatusFilterComparison

Filter by status (ACTIVE, IN_TRIAL, CANCELED, etc.)

customerId · UUIDFilterComparison

Filter by customer internal ID

startDate · DateFieldComparison

Filter by start date

trialEndDate · DateFieldComparison

Filter by trial end date

cancellationDate · DateFieldComparison

Filter by cancellation date

billingId · StringFieldComparison

Filter by billing provider subscription ID

pricingType · PricingTypeFilterComparison

Filter by pricing type (FREE, PAID, CUSTOM)

paging · CursorPaging

Pagination options

Show properties

first · Int

Number of items to fetch

after · String

Cursor to fetch items after

sorting · [SubscriptionQuerySort]

Sorting options

Show properties

field · SubscriptionQuerySortFields · required

Field to sort by: createdAt, startDate, status

direction · SortDirection · required

Sort direction: ASC or DESC

Filter Examples

Active subscriptions only

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

Trials ending soon

{
  "filter": {
    "status": { "eq": "IN_TRIAL" },
    "trialEndDate": {
      "lte": "2024-01-31T23:59:59Z"
    }
  }
}

Canceled in date range

{
  "filter": {
    "status": { "eq": "CANCELED" },
    "cancellationDate": {
      "gte": "2024-01-01T00:00:00Z",
      "lte": "2024-01-31T23:59:59Z"
    }
  }
}

Common Use Cases

Admin dashboard

Display all subscriptions with filtering by status and customer.

Trial conversion tracking

Monitor trials approaching end date for conversion campaigns.

Churn analysis

Query canceled subscriptions for churn reporting.

Related Operations

• Get Subscription - Get single subscription
• Get Active Subscriptions - Get active subscriptions for customer