> ## 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 or custom credit currency.

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

<Warning>
  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`.
</Warning>

## Query

<CodeGroup>
  ```graphql Query theme={null}
  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
        }
      }
    }
  }
  ```

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

  ```json Response theme={null}
  {
    "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"
        }
      }
    }
  }
  ```
</CodeGroup>

<Note>
  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](/guides/quick-start-guides/gating-access-to-features) for the full pattern.
</Note>

## 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">
      The feature's reference ID. Mutually exclusive with `currencyId` — provide this to check a feature entitlement.
    </ParamField>

    <ParamField body="currencyId" type="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.
    </ParamField>

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

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

      <Expandable title="properties">
        <ParamField body="requestedUsage" type="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.
        </ParamField>

        <ParamField body="requestedValues" type="[String]">
          Requested values to evaluate against allowed values, for enum features
        </ParamField>
      </Expandable>
    </ParamField>

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

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

<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",
      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 });
```

<Note>
  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](/guides/quick-start-guides/gating-access-to-features) for details.
</Note>

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


## Related topics

- [Get Entitlements](/api-and-sdks/api-reference/queries/get-entitlements.md)
- [Entitlement](/api-and-sdks/api-reference/types/entitlement.md)
- [Get entitlements state](/api-reference/entitlements/get-entitlements-state.md)
- [Get a list of addon entitlements](/api-reference/addon-entitlements/get-a-list-of-addon-entitlements.md)
- [Get a list of plan entitlements](/api-reference/plan-entitlements/get-a-list-of-plan-entitlements.md)