Subscription entitlements

Overview

The subscription_entitlement object represents the entitlement a subscription holds for a feature. A subscription can have several subscription_entitlements, each tied to a specific feature.

How subscription entitlements are determined

When an entitlement_override is set for a subscription related to a feature, the value of the subscription_entitlement takes on the value of the entitlement_override.

If there isn't an entitlement_override, the value of the subscription_entitlement is based on the entitlements linked to the item_prices within the subscription_items. If an item_price lacks an entitlement record for a particular feature, we consider the entitlement (when available) of its parent item.

The method used to derive the subscription_entitlement from entitlements follows specific rules determined by the feature type. We outline and provide examples of these rules in the sections below:

Sample Subscription entitlementJSON

Subscription entitlements attributes

subscription_id

required, string, max chars=50

The unique identifier of the subscription .

feature_id

optional, string, max chars=50

The unique identifier of the feature .

feature_name

optional, string, max chars=50

The name of the feature .

feature_unit

optional, string, max chars=50

The unit of measure for the feature when its type is either quantity or range .

feature_type

optional, string, max chars=50

Specifies the type of the feature associated with the granted subscription entitlement.

value

optional, string, max chars=50

The value denoting the final entitlement level that the subscription holds for the feature.

See also: How subscription entitlements are determined.

name

optional, string, max chars=50

The display name of the final entitlement level that the subscription holds for the feature. It is derived based on the type of feature as follows: - When feature.type is range or quantity: the name is the space-separated concatenation of value and the pluralized form of feature_unit. For example, if value is 20 and feature_unit is user, then name becomes 20 users.

When feature.type is custom: the name is the same as value.
When feature.type is switch: name is set to Available when value is true; it's set to Not Available when value is false.

is_overridden

required, boolean

Indicates whether the entitlement held by the subscription for the feature is overridden via an entitlement_overrides record.

is_enabled

required, boolean

Indicates that components.is_enabled exists.

expires_at

optional, timestamp(UTC) in seconds

Timestamp when the subscription entitlements are going to expire.

components

optional, component

The component entitlements that constitute this subscription_entitlement. The effective entitlement value and name are determined from these component entitlements.