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

# Entitlement

Represents a customer's entitlement to a feature. Entitlements define what a customer can access and how much they can use based on their subscription.

## Type Definition

```graphql theme={null}
type Entitlement {
  # Access status
  isGranted: Boolean!
  accessDeniedReason: AccessDeniedReason

  # Feature
  feature: EntitlementFeature

  # Usage limits
  usageLimit: Float
  hasUnlimitedUsage: Boolean!
  hasSoftLimit: Boolean
  currentUsage: Float
  requestedUsage: Float

  # Enum values
  enumValues: [String!]
  requestedValues: [String!]

  # Reset period
  resetPeriod: EntitlementResetPeriod
  resetPeriodConfiguration: ResetPeriodConfiguration
  usagePeriodStart: DateTime
  usagePeriodEnd: DateTime
  usagePeriodAnchor: DateTime

  # Credit rate
  creditRate: CreditRate

  # Metering
  meterId: String

  # Display
  displayNameOverride: String
  hiddenFromWidgets: [WidgetType!]

  # Timestamps
  entitlementUpdatedAt: DateTime
  usageUpdatedAt: DateTime
  validUntil: Float
}
```

## Fields

### Access Status

| Field                | Type                                                                               | Description                                     |
| -------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------- |
| `isGranted`          | `Boolean!`                                                                         | Whether the customer has access to this feature |
| `accessDeniedReason` | [`AccessDeniedReason`](/api-and-sdks/api-reference/types/enums#accessdeniedreason) | Reason access was denied (if applicable)        |

### Feature

| Field     | Type                                                              | Description                         |
| --------- | ----------------------------------------------------------------- | ----------------------------------- |
| `feature` | [`EntitlementFeature`](/api-and-sdks/api-reference/types/feature) | The feature this entitlement is for |

### Usage Limits

| Field               | Type       | Description                                  |
| ------------------- | ---------- | -------------------------------------------- |
| `usageLimit`        | `Float`    | Maximum allowed usage                        |
| `hasUnlimitedUsage` | `Boolean!` | Whether usage is unlimited                   |
| `hasSoftLimit`      | `Boolean`  | Whether the limit is soft (usage can exceed) |
| `currentUsage`      | `Float`    | Current usage in the period                  |
| `requestedUsage`    | `Float`    | Usage amount requested by the customer       |

### Enum Values

| Field             | Type        | Description                              |
| ----------------- | ----------- | ---------------------------------------- |
| `enumValues`      | `[String!]` | Allowed enum values for this entitlement |
| `requestedValues` | `[String!]` | Values requested by the customer         |

### Reset Period

| Field                      | Type                                                                                       | Description                   |
| -------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------- |
| `resetPeriod`              | [`EntitlementResetPeriod`](/api-and-sdks/api-reference/types/enums#entitlementresetperiod) | How often usage resets        |
| `resetPeriodConfiguration` | `ResetPeriodConfiguration`                                                                 | Detailed reset configuration  |
| `usagePeriodStart`         | `DateTime`                                                                                 | Start of current usage period |
| `usagePeriodEnd`           | `DateTime`                                                                                 | End of current usage period   |
| `usagePeriodAnchor`        | `DateTime`                                                                                 | Anchor date for usage periods |

### Credit Rate

| Field        | Type         | Description                                    |
| ------------ | ------------ | ---------------------------------------------- |
| `creditRate` | `CreditRate` | Credit rate for this feature (if credit-based) |

## AccessDeniedReason Enum

| Value                                | Description                                     |
| ------------------------------------ | ----------------------------------------------- |
| `CustomerNotFound`                   | The customer was not found                      |
| `CustomerIsArchived`                 | The customer is archived                        |
| `CustomerResourceNotFound`           | The resource was not found                      |
| `FeatureNotFound`                    | The feature does not exist                      |
| `FeatureTypeMismatch`                | The requested entitlement type doesn't match    |
| `NoActiveSubscription`               | No active subscription for the customer         |
| `NoFeatureEntitlementInSubscription` | The subscription doesn't include this feature   |
| `RequestedUsageExceedingLimit`       | The requested usage exceeds the limit           |
| `RequestedValuesMismatch`            | The requested values don't match allowed values |
| `BudgetExceeded`                     | Usage budget has been exceeded                  |
| `InsufficientCredits`                | Not enough credits available                    |
| `Revoked`                            | Entitlement was revoked                         |
| `Unknown`                            | Unknown reason                                  |

## EntitlementResetPeriod Enum

| Value   | Description    |
| ------- | -------------- |
| `MONTH` | Resets monthly |
| `WEEK`  | Resets weekly  |
| `DAY`   | Resets daily   |
| `HOUR`  | Resets hourly  |
| `YEAR`  | Resets yearly  |

## Example Response

### Boolean Entitlement (Granted)

```json theme={null}
{
  "isGranted": true,
  "feature": {
    "refId": "feature-sso",
    "displayName": "Single Sign-On",
    "featureType": "BOOLEAN"
  },
  "hasUnlimitedUsage": false,
  "entitlementUpdatedAt": "2024-01-15T10:30:00Z"
}
```

### Numeric Entitlement (With Usage)

```json theme={null}
{
  "isGranted": true,
  "feature": {
    "refId": "feature-api-calls",
    "displayName": "API Calls",
    "featureType": "NUMBER",
    "featureUnits": "call",
    "featureUnitsPlural": "calls"
  },
  "usageLimit": 10000,
  "hasUnlimitedUsage": false,
  "hasSoftLimit": false,
  "currentUsage": 3500,
  "resetPeriod": "MONTH",
  "usagePeriodStart": "2024-01-01T00:00:00Z",
  "usagePeriodEnd": "2024-02-01T00:00:00Z",
  "entitlementUpdatedAt": "2024-01-15T10:30:00Z",
  "usageUpdatedAt": "2024-01-18T14:22:00Z"
}
```

### Denied Entitlement

```json theme={null}
{
  "isGranted": false,
  "accessDeniedReason": "NoFeatureEntitlementInSubscription",
  "feature": {
    "refId": "feature-advanced-analytics",
    "displayName": "Advanced Analytics",
    "featureType": "BOOLEAN"
  },
  "hasUnlimitedUsage": false
}
```

### Unlimited Entitlement

```json theme={null}
{
  "isGranted": true,
  "feature": {
    "refId": "feature-storage",
    "displayName": "Storage",
    "featureType": "NUMBER",
    "featureUnits": "GB",
    "featureUnitsPlural": "GB"
  },
  "hasUnlimitedUsage": true,
  "currentUsage": 150,
  "entitlementUpdatedAt": "2024-01-15T10:30:00Z"
}
```

## Related Types

* [Feature](/api-and-sdks/api-reference/types/feature) - Feature type
* [Customer](/api-and-sdks/api-reference/types/customer) - Customer type
* [CustomerSubscription](/api-and-sdks/api-reference/types/subscription) - Subscription type

## Related Operations

* [Get Entitlement](/api-and-sdks/api-reference/queries/get-entitlement) - Fetch a single entitlement
* [Get Entitlements](/api-and-sdks/api-reference/queries/get-entitlements) - Fetch all entitlements for a customer
* [Grant Promotional Entitlements](/api-and-sdks/api-reference/mutations/grant-promotional-entitlements) - Grant entitlements
* [Recalculate Entitlements](/api-and-sdks/api-reference/mutations/recalculate-entitlements) - Refresh entitlements