Get Entitlement

Retrieves a specific entitlement for a customer, checking their access to a particular feature or custom credit currency.

To benefit from Stigg’s low-latency capabilities, use the Sidecar — it serves entitlement checks from a local cache without a network round-trip per request, with built-in fallback handling. For Node.js applications, the Node.js SDK provides equivalent low-latency caching natively in-process.

The entitlement query is deprecated. Use entitlementV2 instead — it accepts either featureId or currencyId on the same query, so it can resolve both feature entitlements and credit entitlements (polymorphism support). New integrations should use entitlementV2.

Query

query GetEntitlement($query: FetchEntitlementQuery!) {
  entitlementV2(query: $query) {
    ... on FeatureEntitlement {
      isGranted
      accessDeniedReason
      hasUnlimitedUsage
      usageLimit
      currentUsage
      requestedUsage
      resetPeriod
      usagePeriodStart
      usagePeriodEnd
      hasSoftLimit
      feature {
        refId
        displayName
        featureType
        featureUnits
      }
    }
    ... on CreditEntitlement {
      isGranted
      accessDeniedReason
      usageLimit
      currentUsage
      requestedUsage
      hasSoftLimit
      currency {
        refId
        displayName
      }
    }
  }
}

{
  "query": {
    "customerId": "customer-123",
    "featureId": "feature-api-calls",
    "options": {
      "requestedUsage": 1
    }
  }
}

{
  "data": {
    "entitlementV2": {
      "isGranted": true,
      "accessDeniedReason": null,
      "hasUnlimitedUsage": false,
      "usageLimit": 10000,
      "currentUsage": 4532,
      "requestedUsage": 1,
      "resetPeriod": "MONTH",
      "usagePeriodStart": "2024-01-01T00:00:00Z",
      "usagePeriodEnd": "2024-02-01T00:00:00Z",
      "hasSoftLimit": false,
      "feature": {
        "refId": "feature-api-calls",
        "displayName": "API Calls",
        "featureType": "NUMBER",
        "featureUnits": "call"
      }
    }
  }
}

Passing options.requestedUsage evaluates the check against a specific amount of usage before it’s consumed — the recommended way to gate an action. See Checking, gating, and reporting usage for the full pattern.

Parameters

FetchEntitlementQuery

required

Query parameters for fetching the entitlement

Show properties

String

required

The customer’s reference ID

String

The feature’s reference ID. Mutually exclusive with currencyId — provide this to check a feature entitlement.

String

The custom credit currency’s reference ID. Mutually exclusive with featureId — provide this to check a credit entitlement (e.g. the customer’s credit wallet balance) directly.

String

Resource ID for multi-resource entitlements

EntitlementOptions

Additional options for the entitlement check

Show properties

Float

The amount of usage the customer is about to consume. When provided, isGranted reflects whether granting this amount would stay within the limit — check this before performing the action and before reporting usage, not after.

[String]

Requested values to evaluate against allowed values, for enum features

UUID

Environment ID

Return Type

entitlementV2 returns a union of FeatureEntitlement or CreditEntitlement, depending on whether the query was made with featureId or currencyId. Select fields for each type using inline fragments (... on FeatureEntitlement, ... on CreditEntitlement). Fields common to both:

Field	Type	Description
`isGranted`	Boolean	Whether access is granted
`accessDeniedReason`	AccessDeniedReason	Why access was denied
`usageLimit`	Float	Maximum allowed usage
`currentUsage`	Float	Current consumption
`requestedUsage`	Float	The usage amount that was requested via `options.requestedUsage`
`hasSoftLimit`	Boolean	Soft vs hard limit

FeatureEntitlement-only fields:

Field	Type	Description
`hasUnlimitedUsage`	Boolean	No usage cap
`resetPeriod`	EntitlementResetPeriod	When usage resets
`usagePeriodStart`	DateTime	Current period start
`usagePeriodEnd`	DateTime	Current period end
`feature`	EntitlementFeature	The feature details

CreditEntitlement-only fields:

Field	Type	Description
`currency`	CreditCurrency	The custom credit currency details

Access Denied Reasons

Reason	Description
`NoActiveSubscription`	No active subscription
`NoFeatureEntitlementInSubscription`	Feature not in plan
`RequestedUsageExceedingLimit`	Would exceed limit
`RequestedValuesMismatch`	Requested values don’t match allowed enum values
`CustomerNotFound`	Customer doesn’t exist
`CustomerIsArchived`	Customer is archived
`CustomerResourceNotFound`	Resource doesn’t exist
`FeatureNotFound`	Feature doesn’t exist
`FeatureTypeMismatch`	Requested entitlement type doesn’t match the feature
`EntitlementNotFound`	No entitlement found for the given feature or currency
`BudgetExceeded`	Usage budget has been exceeded
`InsufficientCredits`	Not enough credits
`Revoked`	Entitlement was revoked
`Unknown`	Unknown reason

Common Use Cases

Feature gating

Check access before showing/enabling a feature.

Usage checking

Verify if customer can perform an action based on usage limits.

Upgrade prompts

Check limits to show upgrade prompts when approaching limits.

Example: Check Before Action

const { data } = await client.query({
  query: GET_ENTITLEMENT,
  variables: {
    query: {
      customerId: user.customerId,
      featureId: "feature-api-calls",
      options: {
        requestedUsage: 1 // the amount this action is about to consume
      }
    }
  }
});

const { isGranted, accessDeniedReason } = data.entitlementV2;

if (!isGranted) {
  console.log(`Access denied: ${accessDeniedReason}`);
  showUpgradePrompt();
  return;
}

// Proceed with the action, then report the usage it consumed
performAction();
await reportUsage({ customerId: user.customerId, featureId: "feature-api-calls", value: 1 });

Checking with requestedUsage set to the exact amount you’re about to consume is what makes the gate accurate — checking currentUsage >= usageLimit against a stale cached value, or reporting usage before gating, can let one extra request through on a hard limit. See Checking, gating, and reporting usage for details.

Get Entitlements - Get all entitlements
Entitlements State - Get entitlements with access state
Report Usage - Report usage

Overview

SDKs

Queries

Mutations

Types

Get Entitlement

Query

Parameters

Return Type

Access Denied Reasons

Common Use Cases

Example: Check Before Action

​Query

​Parameters

​Return Type

​Access Denied Reasons

​Common Use Cases

​Example: Check Before Action

​Related Operations

Query

Parameters

Return Type

Access Denied Reasons

Common Use Cases

Example: Check Before Action

Related Operations