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

# Fetching subscriptions — methods compared

Stigg exposes three distinct ways to fetch a customer's subscriptions. They differ in speed, data richness, filtering capabilities, and — critically — in how they handle edge cases. Choosing the wrong method, or not accounting for known SDK quirks, can cause subtle runtime errors.

## Overview

| Method                       | Interface | Speed       | Returns when empty | Scope without `resourceId` |
| ---------------------------- | --------- | ----------- | ------------------ | -------------------------- |
| `getActiveSubscriptionsList` | Edge SDK  | **Fastest** | Empty list         | Global subscriptions only  |
| `getActiveSubscriptions`     | GraphQL   | Fast        | Empty list         | Global subscriptions only  |
| `subscriptions`              | GraphQL   | Slower      | Empty list         | All subscriptions (admin)  |

## `getActiveSubscriptionsList` — Edge SDK

This method is served directly from the Stigg Edge (local sidecar cache) and is by far the fastest option. It returns slim subscription objects; for full subscription details use `getSubscription` instead.

It accepts a single `resourceId`, a list of resource IDs (up to 100), or no resource ID at all.

* Without `resourceId`: returns only global (non-resource-attached) subscriptions.
* With `resourceId`: returns the active subscriptions for the specified resource(s).

<CodeGroup>
  ```typescript Node.js theme={null}
  // Global subscriptions
  const subscriptions = await stiggClient.getActiveSubscriptionsList({
    customerId: 'customer-demo-01',
  });

  // Single resource
  const subscriptions = await stiggClient.getActiveSubscriptionsList({
    customerId: 'customer-demo-01',
    resourceId: 'resource-01',
  });

  // Multiple resources
  const subscriptions = await stiggClient.getActiveSubscriptionsList({
    customerId: 'customer-demo-01',
    resourceId: ['resource-01', 'resource-02'],
  });
  ```

  ```go Go theme={null}
  result, err := client.GetActiveSubscriptionList(context.Background(), stigg.GetActiveSubscriptionListInput{
    CustomerID: "customer-demo-01",
    ResourceID: Ptr("resource-01"), // optional
  })
  ```
</CodeGroup>

**Prefer this method** when you only need to know what subscriptions are currently active and don't need the full subscription payload. It is the recommended method for runtime entitlement checks and UI rendering.

## `getActiveSubscriptions` — GraphQL

The full-fidelity GraphQL equivalent. Returns complete subscription objects including plan details, billing periods, add-ons, and pricing. Use this when you need the full subscription payload and are willing to accept the higher latency of a GraphQL round-trip.

* Without `resourceId`: returns only global (non-resource-attached) subscriptions for the customer. It does **not** return subscriptions attached to resources.
* With `resourceId`: returns active subscriptions for that specific resource.

<CodeGroup>
  ```graphql GraphQL theme={null}
  query GetActiveSubscriptions($input: GetActiveSubscriptionsInput!) {
    getActiveSubscriptions(input: $input) {
      subscriptionId
      status
      plan { refId displayName }
    }
  }
  ```

  ```go Go theme={null}
  result, err := client.GetActiveSubscriptions(context.Background(), stigg.GetActiveSubscriptionsInput{
    CustomerID: "customer-demo-01",
    ResourceID: Ptr("resource-01"), // optional
  })
  ```
</CodeGroup>

<Note>
  The GraphQL `getActiveSubscriptions` query correctly returns an empty list when there are no active subscriptions. The Go SDK wrapper `GetActiveSubscriptions` does not.
</Note>

## `subscriptions` — GraphQL (admin)

A paginated, filterable query over all subscriptions regardless of status. Use this for admin dashboards, churn analysis, or any reporting that needs to go beyond just the currently active subscriptions.

It is slower than `getActiveSubscriptions` and is not suitable for runtime per-customer checks.

<CodeGroup>
  ```graphql GraphQL theme={null}
  query ListSubscriptions($filter: SubscriptionQueryFilter, $paging: CursorPaging, $sorting: [SubscriptionQuerySort!]) {
    subscriptions(filter: $filter, paging: $paging, sorting: $sorting) {
      edges { node { subscriptionId status plan { refId } } }
      pageInfo { hasNextPage endCursor }
    }
  }
  ```

  ```go Go theme={null}
  result, err := client.GetSubscriptions(context.Background(), stigg.GetSubscriptionsInput{
    Filter:  &filter,
    Paging:  &stigg.CursorPaging{First: Ptr(20)},
    Sorting: []*stigg.SubscriptionSort{{Field: "createdAt", Direction: "DESC"}},
  })
  ```
</CodeGroup>

<Note>
  The GraphQL `subscriptions` query correctly returns an empty list when no subscriptions match the filter.
</Note>

## Choosing the right method

* **For runtime entitlement checks and UI rendering**: use `getActiveSubscriptionsList` — it's Edge-cached and fastest.
* **For fetching full subscription detail at runtime**: use `getActiveSubscriptions` via GraphQL.
* **For admin reporting, dashboards, or filtering by status/dates**: use `subscriptions` via GraphQL.
* **When using the Go SDK**: always handle the empty-result error from all three methods, and always pass explicit `Paging` and `Sorting` to `GetSubscriptions`.

## `resourceId` scoping behaviour

Both `getActiveSubscriptionsList` and `getActiveSubscriptions` are resource-scoped:

* Omitting `resourceId` returns only **global subscriptions** — subscriptions that were provisioned without a resource ID (i.e. for products with the "single active subscription" type).
* To retrieve subscriptions for a resource-backed product (products with the "multiple active subscriptions" type), you **must** pass the corresponding `resourceId`.

This means that if your product catalog includes both global and resource-backed products, you need separate calls — one without `resourceId` for global subscriptions, and one with a `resourceId` per resource — to get the complete picture.

The admin `subscriptions` query is not scoped this way and returns all matching subscriptions regardless of whether they have a resource attached.