Get Active Subscriptions

Retrieves all active subscriptions for a specific customer, optionally filtered by product or resource.

resourceId scoping: when resourceId is not provided, this query returns only global subscriptions — subscriptions provisioned without a resource ID (i.e. for products with the “single active subscription” type). It does not return subscriptions attached to a resource. Pass a resourceId to retrieve active subscriptions for a specific resource-backed product instance.

Performance: for runtime use cases (e.g. checking a customer’s current plan in your app), consider using getActiveSubscriptionsList via the Edge SDK instead. It serves results from a local cache and is significantly faster than this GraphQL query. See Fetching subscriptions — methods compared.

Query

Query

query GetActiveSubscriptions($input: GetActiveSubscriptionsInput!) {
  getActiveSubscriptions(input: $input) {
    subscriptionId
    status
    startDate
    endDate
    effectiveEndDate
    currentBillingPeriodStart
    currentBillingPeriodEnd
    billingPeriod
    additionalMetaData
    customer {
      customerId
      email
    }
    payingCustomer {
      customerId
      email
    }
    plan {
      refId
      displayName
      description
      product {
        refId
        displayName
        downgradePlan {
          refId
          displayName
        }
      }
    }
    addons {
      addon {
        refId
        displayName
      }
      quantity
    }
    prices {
      billingModel
      price {
        billingPeriod
        price {
          amount
          currency
        }
      }
    }
    totalPrice {
      subTotal {
        amount
        currency
      }
      total {
        amount
        currency
      }
    }
    trialEndDate
  }
}

{
  "input": {
    "customerId": "customer-123"
  }
}

{
  "data": {
    "getActiveSubscriptions": [
      {
        "subscriptionId": "sub-456",
        "status": "ACTIVE",
        "startDate": "2024-01-15T00:00:00Z",
        "endDate": null,
        "effectiveEndDate": "2025-01-15T00:00:00Z",
        "currentBillingPeriodStart": "2024-01-15T00:00:00Z",
        "currentBillingPeriodEnd": "2024-02-15T00:00:00Z",
        "billingPeriod": "MONTHLY",
        "additionalMetaData": {
          "internalTierId": "tier-gold"
        },
        "customer": {
          "customerId": "customer-123",
          "email": "[e-mail]"
        },
        "payingCustomer": {
          "customerId": "customer-123",
          "email": "[e-mail]"
        },
        "plan": {
          "refId": "plan-pro",
          "displayName": "Pro Plan",
          "description": "Full access to all Pro features",
          "product": {
            "refId": "product-main",
            "displayName": "Main Product",
            "downgradePlan": {
              "refId": "plan-free",
              "displayName": "Free Plan"
            }
          }
        },
        "addons": [
          {
            "addon": {
              "refId": "addon-seats",
              "displayName": "Extra Seats"
            },
            "quantity": 5
          }
        ],
        "prices": [
          {
            "billingModel": "FLAT_FEE",
            "price": {
              "billingPeriod": "MONTHLY",
              "price": {
                "amount": 99,
                "currency": "USD"
              }
            }
          }
        ],
        "totalPrice": {
          "subTotal": {
            "amount": 99,
            "currency": "USD"
          },
          "total": {
            "amount": 99,
            "currency": "USD"
          }
        },
        "trialEndDate": null
      }
    ]
  }
}

Parameters

input · GetActiveSubscriptionsInput · required

Input parameters for retrieving active subscriptions

Show properties

customerId · String · required

The unique customer reference ID

resourceId · String

Filter by specific resource ID (for multi-resource customers)

productId · String

Filter by product reference ID

environmentId · UUID

The environment ID. If not provided, uses the environment from your API key.

Return Type

Returns an array of CustomerSubscription objects with:

Field	Type	Description
subscriptionId	String	Unique subscription ID
status	SubscriptionStatus	ACTIVE or IN_TRIAL
startDate	DateTime	When subscription started
endDate	DateTime	End date of the subscription
effectiveEndDate	DateTime	Effective end date, accounting for cancellation or trial end behavior
currentBillingPeriodStart	DateTime	Start date of the current billing period
currentBillingPeriodEnd	DateTime	Current period end
billingPeriod	BillingPeriod	Billing cadence (e.g. MONTHLY, ANNUALLY)
additionalMetaData	JSON	Custom metadata (key-value pairs) attached to the subscription
customer	Customer	The subscription’s customer, including customerId and email
payingCustomer	Customer	The paying customer (for payment delegation scenarios), including customerId and email
plan	Plan	The subscribed plan, including refId, displayName, description, and nested product with refId, displayName, and downgradePlan
addons	[SubscriptionAddon]	Applied addons
prices	[Price]	List of price items, each with billingModel and price (containing billingPeriod and nested price with amount, currency)
totalPrice	TotalPrice	Simplified total with subTotal and total (each containing amount and currency). Does not account for per-unit quantities, discounts, minimum spend, or usage-based pricing
trialEndDate	DateTime	Trial end (if applicable)

Common Use Cases

Determine current access

Check what plan(s) a customer currently has access to.

Multi-product access

For products with multiple subscription products, get all active subscriptions.

Display current plan

Show the customer their current subscription in your app.

Example: Check Customer Access

const { data } = await client.query({
  query: GET_ACTIVE_SUBSCRIPTIONS,
  variables: {
    input: { customerId: user.customerId }
  }
});

const subscriptions = data.getActiveSubscriptions;

if (subscriptions.length === 0) {
  // No active subscription - show upgrade prompt
  showUpgradePrompt();
} else {
  const currentPlan = subscriptions[0].plan;
  console.log(`Current plan: ${currentPlan.displayName}`);
}

Related Operations

• Get Subscription - Get single subscription details
• List Subscriptions - Query all subscriptions with filters
• Entitlements State - Get customer entitlements