Skip to main content
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

MethodInterfaceSpeedReturns when emptyScope without resourceId
getActiveSubscriptionsListEdge SDKFastestEmpty listGlobal subscriptions only
getActiveSubscriptionsGraphQLFastEmpty listGlobal subscriptions only
subscriptionsGraphQLSlowerEmpty listAll 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).
// 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'],
});
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.
Go SDK bug: GetActiveSubscriptionList returns an error instead of an empty list when the customer has no active subscriptions. The error message reads "Customer resource not found", which is misleading — it does not mean the customer itself is missing, only that no subscriptions were found. This is a known bug confirmed by Stigg support. Always handle this error explicitly in Go code by treating it as an empty result.

​
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.
query GetActiveSubscriptions($input: GetActiveSubscriptionsInput!) {
  getActiveSubscriptions(input: $input) {
    subscriptionId
    status
    plan { refId displayName }
  }
}
The GraphQL getActiveSubscriptions query correctly returns an empty list when there are no active subscriptions. The Go SDK wrapper GetActiveSubscriptions does not — see the warning above under getActiveSubscriptionsList.

​
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. 
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 SDK bug: GetSubscriptions requires explicit Paging and Sorting arguments even if you do not intend to paginate or sort. Omitting them causes a runtime error. This is a known bug confirmed by Stigg support; always supply both arguments.Additionally, like GetActiveSubscriptions and GetActiveSubscriptionList, GetSubscriptions returns an error instead of an empty list when no results are found. The misleading error "Customer resource not found" should be treated as an empty result.
The GraphQL subscriptions query correctly returns an empty list when no subscriptions match the filter.

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