Skip to main content
Retrieves a specific entitlement for a customer, checking their access to a particular feature.

​
Query

query GetEntitlement($query: FetchEntitlementQuery!) {
  entitlement(query: $query) {
    isGranted
    hasUnlimitedUsage
    usageLimit
    currentUsage
    resetPeriod
    usagePeriodStart
    usagePeriodEnd
    hasSoftLimit
    accessDeniedReason
    feature {
      refId
      displayName
      featureType
      featureUnits
    }
  }
}

​
Parameters

​
query
FetchEntitlementQuery
required
Query parameters for fetching the entitlement

​
Return Type

Returns an Entitlement object with:
FieldTypeDescription
isGrantedBooleanWhether access is granted
hasUnlimitedUsageBooleanNo usage cap
usageLimitFloatMaximum allowed usage
currentUsageFloatCurrent consumption
resetPeriodEntitlementResetPeriodWhen usage resets
usagePeriodStartDateTimeCurrent period start
usagePeriodEndDateTimeCurrent period end
hasSoftLimitBooleanSoft vs hard limit
accessDeniedReasonAccessDeniedReasonWhy access was denied
featureEntitlementFeatureThe feature details

​
Access Denied Reasons

ReasonDescription
NoActiveSubscriptionNo active subscription
NoFeatureEntitlementInSubscriptionFeature not in plan
RequestedUsageExceedingLimitWould exceed limit
CustomerNotFoundCustomer doesn’t exist
FeatureNotFoundFeature doesn’t exist
CustomerIsArchivedCustomer is archived
InsufficientCreditsNot enough credits

​
Common Use Cases

Check access before showing/enabling a feature.
Verify if customer can perform an action based on usage limits.
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"
    }
  }
});

const { isGranted, currentUsage, usageLimit, accessDeniedReason } = data.entitlement;

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

if (currentUsage >= usageLimit) {
  console.log("Usage limit reached");
  showLimitReachedMessage();
  return;
}

// Proceed with action
performAction();