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

# Get Entitlement

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

<Tip>
  To benefit from Stigg's low-latency capabilities, use the [Sidecar](/api-and-sdks/integration/backend/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](https://node-sdk-docs.stigg.io/classes/stigg) provides equivalent low-latency caching natively in-process.
</Tip>

## Query

<CodeGroup>
  ```graphql Query theme={null}
  query GetEntitlement($query: FetchEntitlementQuery!) {
    entitlement(query: $query) {
      isGranted
      hasUnlimitedUsage
      usageLimit
      currentUsage
      resetPeriod
      usagePeriodStart
      usagePeriodEnd
      hasSoftLimit
      accessDeniedReason
      feature {
        refId
        displayName
        featureType
        featureUnits
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "query": {
      "customerId": "customer-123",
      "featureId": "feature-api-calls"
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "entitlement": {
        "isGranted": true,
        "hasUnlimitedUsage": false,
        "usageLimit": 10000,
        "currentUsage": 4532,
        "resetPeriod": "MONTH",
        "usagePeriodStart": "2024-01-01T00:00:00Z",
        "usagePeriodEnd": "2024-02-01T00:00:00Z",
        "hasSoftLimit": false,
        "accessDeniedReason": null,
        "feature": {
          "refId": "feature-api-calls",
          "displayName": "API Calls",
          "featureType": "NUMBER",
          "featureUnits": "call"
        }
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="query" type="FetchEntitlementQuery" required>
  Query parameters for fetching the entitlement

  <Expandable title="properties">
    <ParamField body="customerId" type="String" required>
      The customer's reference ID
    </ParamField>

    <ParamField body="featureId" type="String" required>
      The feature's reference ID
    </ParamField>

    <ParamField body="resourceId" type="String">
      Resource ID for multi-resource entitlements
    </ParamField>

    <ParamField body="options" type="EntitlementOptions">
      Additional options for the entitlement check
    </ParamField>

    <ParamField body="environmentId" type="UUID">
      Environment ID
    </ParamField>
  </Expandable>
</ParamField>

## Return Type

Returns an `Entitlement` object with:

| Field                | Type                   | Description               |
| -------------------- | ---------------------- | ------------------------- |
| `isGranted`          | Boolean                | Whether access is granted |
| `hasUnlimitedUsage`  | Boolean                | No usage cap              |
| `usageLimit`         | Float                  | Maximum allowed usage     |
| `currentUsage`       | Float                  | Current consumption       |
| `resetPeriod`        | EntitlementResetPeriod | When usage resets         |
| `usagePeriodStart`   | DateTime               | Current period start      |
| `usagePeriodEnd`     | DateTime               | Current period end        |
| `hasSoftLimit`       | Boolean                | Soft vs hard limit        |
| `accessDeniedReason` | AccessDeniedReason     | Why access was denied     |
| `feature`            | EntitlementFeature     | The feature details       |

## Access Denied Reasons

| Reason                               | Description            |
| ------------------------------------ | ---------------------- |
| `NoActiveSubscription`               | No active subscription |
| `NoFeatureEntitlementInSubscription` | Feature not in plan    |
| `RequestedUsageExceedingLimit`       | Would exceed limit     |
| `CustomerNotFound`                   | Customer doesn't exist |
| `FeatureNotFound`                    | Feature doesn't exist  |
| `CustomerIsArchived`                 | Customer is archived   |
| `InsufficientCredits`                | Not enough credits     |

## Common Use Cases

<AccordionGroup>
  <Accordion title="Feature gating">
    Check access before showing/enabling a feature.
  </Accordion>

  <Accordion title="Usage checking">
    Verify if customer can perform an action based on usage limits.
  </Accordion>

  <Accordion title="Upgrade prompts">
    Check limits to show upgrade prompts when approaching limits.
  </Accordion>
</AccordionGroup>

## Example: Check Before Action

```javascript theme={null}
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();
```

## Related Operations

* [Get Entitlements](/api-and-sdks/api-reference/queries/get-entitlements) - Get all entitlements
* [Entitlements State](/api-and-sdks/api-reference/queries/entitlements-state) - Get entitlements with access state
* [Report Usage](/api-and-sdks/api-reference/mutations/report-usage) - Report usage