Skip to main content
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

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

FieldTypeDescription
isGrantedBoolean!Whether the customer has access to this feature
accessDeniedReasonAccessDeniedReasonReason access was denied (if applicable)

​
Feature

FieldTypeDescription
featureEntitlementFeatureThe feature this entitlement is for

​
Usage Limits

FieldTypeDescription
usageLimitFloatMaximum allowed usage
hasUnlimitedUsageBoolean!Whether usage is unlimited
hasSoftLimitBooleanWhether the limit is soft (usage can exceed)
currentUsageFloatCurrent usage in the period
requestedUsageFloatUsage amount requested by the customer

​
Enum Values

FieldTypeDescription
enumValues[String!]Allowed enum values for this entitlement
requestedValues[String!]Values requested by the customer

​
Reset Period

FieldTypeDescription
resetPeriodEntitlementResetPeriodHow often usage resets
resetPeriodConfigurationResetPeriodConfigurationDetailed reset configuration
usagePeriodStartDateTimeStart of current usage period
usagePeriodEndDateTimeEnd of current usage period
usagePeriodAnchorDateTimeAnchor date for usage periods

​
Credit Rate

FieldTypeDescription
creditRateCreditRateCredit rate for this feature (if credit-based)

​
AccessDeniedReason Enum

ValueDescription
CustomerNotFoundThe customer was not found
CustomerIsArchivedThe customer is archived
CustomerResourceNotFoundThe resource was not found
FeatureNotFoundThe feature does not exist
FeatureTypeMismatchThe requested entitlement type doesn’t match
NoActiveSubscriptionNo active subscription for the customer
NoFeatureEntitlementInSubscriptionThe subscription doesn’t include this feature
RequestedUsageExceedingLimitThe requested usage exceeds the limit
RequestedValuesMismatchThe requested values don’t match allowed values
BudgetExceededUsage budget has been exceeded
InsufficientCreditsNot enough credits available
RevokedEntitlement was revoked
UnknownUnknown reason

​
EntitlementResetPeriod Enum

ValueDescription
MONTHResets monthly
WEEKResets weekly
DAYResets daily
HOURResets hourly
YEARResets yearly

​
Example Response

​
Boolean Entitlement (Granted)

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

​
Numeric Entitlement (With Usage)

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

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

​
Unlimited Entitlement

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