> ## 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 Subscriptions

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

## Query

<CodeGroup>
  ```graphql Query theme={null}
  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
    }
  }
  ```

  ```json Variables theme={null}
  {
    "filter": {
      "status": { "in": ["ACTIVE", "IN_TRIAL"] }
    },
    "paging": {
      "first": 20
    },
    "sorting": [
      { "field": "createdAt", "direction": "DESC" }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "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
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="filter" type="SubscriptionQueryFilter">
  Filter criteria for subscriptions

  <Expandable title="properties">
    <ParamField body="subscriptionId" type="StringFieldComparison">
      Filter by subscription ID
    </ParamField>

    <ParamField body="status" type="SubscriptionStatusFilterComparison">
      Filter by status (ACTIVE, IN\_TRIAL, CANCELED, etc.)
    </ParamField>

    <ParamField body="customerId" type="UUIDFilterComparison">
      Filter by customer internal ID
    </ParamField>

    <ParamField body="startDate" type="DateFieldComparison">
      Filter by start date
    </ParamField>

    <ParamField body="trialEndDate" type="DateFieldComparison">
      Filter by trial end date
    </ParamField>

    <ParamField body="cancellationDate" type="DateFieldComparison">
      Filter by cancellation date
    </ParamField>

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

    <ParamField body="pricingType" type="PricingTypeFilterComparison">
      Filter by pricing type (FREE, PAID, CUSTOM)
    </ParamField>
  </Expandable>
</ParamField>

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

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

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

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

  <Expandable title="properties">
    <ParamField body="field" type="SubscriptionQuerySortFields" required>
      Field to sort by: `createdAt`, `startDate`, `status`
    </ParamField>

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

## Filter Examples

### Active subscriptions only

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

### Trials ending soon

```json theme={null}
{
  "filter": {
    "status": { "eq": "IN_TRIAL" },
    "trialEndDate": {
      "lte": "2024-01-31T23:59:59Z"
    }
  }
}
```

### Canceled in date range

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

## Common Use Cases

<AccordionGroup>
  <Accordion title="Admin dashboard">
    Display all subscriptions with filtering by status and customer.
  </Accordion>

  <Accordion title="Trial conversion tracking">
    Monitor trials approaching end date for conversion campaigns.
  </Accordion>

  <Accordion title="Churn analysis">
    Query canceled subscriptions for churn reporting.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Get Subscription](/api-and-sdks/api-reference/queries/get-subscription) - Get single subscription
* [Get Active Subscriptions](/api-and-sdks/api-reference/queries/get-active-subscriptions) - Get active subscriptions for customer