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

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	Reason access was denied (if applicable)

Feature

Field	Type	Description
feature	EntitlementFeature	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	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)

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

Related Types

• Feature - Feature type
• Customer - Customer type
• CustomerSubscription - Subscription type

Related Operations

• Get Entitlement - Fetch a single entitlement
• Get Entitlements - Fetch all entitlements for a customer
• Grant Promotional Entitlements - Grant entitlements
• Recalculate Entitlements - Refresh entitlements