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

# Entitlements State

Retrieves all entitlements for a customer along with the overall access state, including reasons for denied access.

<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 GetEntitlementsState($query: FetchEntitlementsQuery!) {
    entitlementsState(query: $query) {
      accessDeniedReason
      entitlements {
        feature {
          refId
          displayName
          featureType
          featureUnits
        }
        isGranted
        hasUnlimitedUsage
        usageLimit
        currentUsage
        resetPeriod
        usagePeriodEnd
        accessDeniedReason
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "query": {
      "customerId": "customer-123"
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "entitlementsState": {
        "accessDeniedReason": null,
        "entitlements": [
          {
            "feature": {
              "refId": "feature-api-calls",
              "displayName": "API Calls",
              "featureType": "NUMBER",
              "featureUnits": "call"
            },
            "isGranted": true,
            "hasUnlimitedUsage": false,
            "usageLimit": 10000,
            "currentUsage": 4532,
            "resetPeriod": "MONTH",
            "usagePeriodEnd": "2024-02-01T00:00:00Z",
            "accessDeniedReason": null
          },
          {
            "feature": {
              "refId": "feature-sso",
              "displayName": "Single Sign-On",
              "featureType": "BOOLEAN",
              "featureUnits": null
            },
            "isGranted": true,
            "hasUnlimitedUsage": false,
            "usageLimit": null,
            "currentUsage": null,
            "resetPeriod": null,
            "usagePeriodEnd": null,
            "accessDeniedReason": null
          }
        ]
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="query" type="FetchEntitlementsQuery" required>
  Query parameters for fetching entitlements state

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

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

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

## Return Type

Returns an `EntitlementsState` object with:

| Field                | Type                                | Description                 |
| -------------------- | ----------------------------------- | --------------------------- |
| `accessDeniedReason` | EntitlementsStateAccessDeniedReason | Global access denial reason |
| `entitlements`       | \[Entitlement]                      | List of entitlements        |

### Global Access Denied Reasons

| Reason                 | Description            |
| ---------------------- | ---------------------- |
| `CustomerNotFound`     | Customer doesn't exist |
| `CustomerIsArchived`   | Customer is archived   |
| `NoActiveSubscription` | No active subscription |

## Common Use Cases

<AccordionGroup>
  <Accordion title="App initialization">
    Recommended for initial entitlement fetch - provides both entitlements and overall access state.
  </Accordion>

  <Accordion title="Handle edge cases">
    Global `accessDeniedReason` helps handle cases where customer has no subscription.
  </Accordion>
</AccordionGroup>

## Example: Handling Access State

```javascript theme={null}
const { data } = await client.query({
  query: GET_ENTITLEMENTS_STATE,
  variables: {
    query: { customerId: user.customerId }
  }
});

const { accessDeniedReason, entitlements } = data.entitlementsState;

if (accessDeniedReason === 'CustomerNotFound') {
  // Customer doesn't exist in Stigg
  redirectToSignup();
  return;
}

if (accessDeniedReason === 'NoActiveSubscription') {
  // Customer exists but needs a subscription
  showPricingPage();
  return;
}

if (accessDeniedReason === 'CustomerIsArchived') {
  // Customer account is deactivated
  showReactivationPrompt();
  return;
}

// Process entitlements normally
initializeFeatureFlags(entitlements);
```

## Related Operations

* [Get Entitlements](/api-and-sdks/api-reference/queries/get-entitlements) - Get entitlements without state
* [Get Entitlement](/api-and-sdks/api-reference/queries/get-entitlement) - Get specific entitlement