Subscription Entitlements
In subscriptions, you can add entitlements to features that are not part of the product catalog items. Additionally, you can also change the entitlement level of an existing feature. Entitlements assigned at the subscription level take precedence over entitlements assigned at the product catalog level. This allows you to override the feature entitlements granted at the product catalog level and control to what extent a user can access or utilize these features. How Chargebee derives subscription entitlements, and how you can override them, depends on whether the feature is metered or non-metered. Your application can keep its copy of the entitlements in sync through webhooks and the API.
Example
Let’s take an example to understand this better. John Doe has three plans available in Chargebee—Starter, Performance, and Enterprise—each offering different levels of entitlements. For the Starter plan, three features are available; the Performance plan includes four features; and the Enterprise plan has five features. John decides to subscribe to the Starter plan.
However, John insists on having the Advanced Analytics feature, which is not part of the Starter plan. This is achieved by overriding John's entitlements on the Starter plan at the subscription level by the account manager.
Subscription entitlements for metered and non-metered features
A subscription gets its entitlements from its plans, addons, and charges, and from any overrides. How Chargebee derives subscription entitlements, and how you can override them, depends on the kind of feature.
Metered features
The subscription entitlement of a metered feature is its included usage.
- How Chargebee derives them: The subscription gets the included usage of its plan prices and non-metered addon prices, which you set when you link pricing for the metered feature. By default, metered addons have unlimited entitlements, which don't count toward the included usage. When you change the included usage of a plan or non-metered addon price, the change applies only to new subscriptions by default. See Grandfathering included usage for metered features. When more than one plan or non-metered addon price on the subscription grants included usage of the same metered feature, Chargebee adds the values to get the total included usage. See How is the total value of quantity-based entitlements calculated?
- How you override them: To change the included usage for one subscription, override the entitlement of a plan or non-metered addon price on that subscription. See Item Price Entitlement Overrides. This differs from non-metered features, whose entitlements you can override directly for the whole subscription, so the steps in Edit Entitlements in Subscriptions, Add Entitlements in Subscriptions, and Remove Entitlements in Subscriptions apply only to non-metered features.
Chargebee tracks usage against the included usage in real time from the usage events you send. If the subscription has a metered addon for the feature, the addon charges for the overage on the invoice. To retrieve the included usage, total usage, and overage (on-demand usage) of the current usage period, use the Usage Charges API.
Non-metered features
The subscription entitlement of a non-metered feature is the access the customer has.
- How Chargebee derives them: Each plan, addon, and charge on the subscription contributes the entitlement set on its item price, or the entitlement set on its item when the item price has none. When more than one item contributes an entitlement to the same quantity-type feature, Chargebee adds the values. See How is the total value of quantity-based entitlements calculated?
- How you override them: Override an entitlement for the whole subscription, permanently or until a date you choose. See Edit Entitlements in Subscriptions, Add Entitlements in Subscriptions, and Remove Entitlements in Subscriptions. A subscription-level override takes precedence over the entitlements from your product catalog. You can also override the entitlement of a plan or addon price on the subscription. See Item Price Entitlement Overrides.
Your application reads the entitlements from Chargebee, grants access, and tracks usage. Non-metered entitlements don't affect invoices.
For more on metered features, see How do entitlements work with usage-based billing?
View Entitlements in Subscriptions
When a feature is activated and mapped to product catalog items, it becomes available for all subscriptions that have said product catalog items. All features available on a subscription are listed in the entitlements section of the subscription detail page.
By default, feature name, entitlement level, and status are displayed in the entitlement section of the subscription.
To view entitlements on the subscription, click the Subscriptions page > select a subscription > scroll down to the Entitlements section.
Features that are overridden at the subscription level appear with an OVERRIDDEN label next to them in the entitlements section of the subscription. To know more about overriding a feature, see Managing Product Entitlements.
Keep subscription entitlements in sync with your application
Your application enforces access, so it needs the current entitlements of each subscription. The subscription object and the subscription_changed event don't include entitlements. Instead, listen for the entitlement webhooks, and then call the List Subscription Entitlements API to refresh the entitlements your application stores.
Chargebee sends the following webhooks when the entitlements of a subscription can change:
subscription_entitlements_createdsubscription_entitlements_updatedentitlement_overrides_updatedentitlement_overrides_removedentitlement_overrides_auto_removeditem_entitlements_updateditem_entitlements_removeditem_price_entitlements_updateditem_price_entitlements_removedcustomer_entitlements_updated
To keep your application in sync, follow these steps:
- Configure a webhook endpoint that receives these events.
- When you receive an event for a subscription, call List Subscription Entitlements for that subscription, and replace the entitlements your application stores. The list results are paginated, so page through them to get every subscription entitlement, including those beyond the first 100 in the event payload.
- When you receive an item or item price event, refresh the entitlements of the subscriptions that include the affected item or item price.
For a metered feature, the subscription entitlement is the included usage. To retrieve usage against it for the current usage period, use the Usage Charges API.
Edit Entitlements in Subscriptions
The edit entitlements function helps you to change the entitlement level of an already existing feature in a subscription. It also allows you to add features that aren't already available on the subscription. These steps apply to non-metered features. To change the included usage of a metered feature, see Item Price Entitlement Overrides. There might be instances when you want to change the entitlement levels of the product catalog items. For example, you want to upgrade the entitlement level of a feature to help users understand their requirements.
To edit entitlements of an already existing feature, follow these steps:
-
Click the Subscriptions page > Entitlements > Click Edit.
-
On the Features list page, click on the feature whose entitlement level you want to change.
-
Select the new entitlement level. Use the toggle button to enable or disable an entitlement. If you want to add the entitlement permanently, select Forever. If you're going to set it for a limited time, select Until, choose a date when you want the entitlement to expire, and click Override.
-
Click Confirm to save the changes.
-
The feature whose entitlement level is overridden at the subscription level has a label OVERRIDDEN in the entitlements section of the subscription details page.
When applying a limited-period override for a specific time period, you can only choose a date in the future.
Add Entitlements in Subscriptions
You can add entitlements to features through the subscription details page. If there are no feature entitlements available in a subscription, you are prompted to create one. These steps apply to non-metered features.
- Use bulk operations to import Subscription Entitlements and Subscription Overrides in Chargebee.
- Depending on your business need, you can add entitlements to your subscription for a limited period or permanently. Read more about limited-period subscriptions here.
To add entitlements to a feature from the subscription screen, follow these steps:
-
Click the Subscriptions list page.
-
Select a subscription whose entitlements you want to override > Scroll down to the entitlement section.
-
Click Add Entitlements. It redirects you to the Features list page.
-
Click + to add the feature to this subscription. If you want to add the entitlement permanently, select Forever. If you're going to set it for a limited time, select Until, and choose a date when you want the entitlement to expire. Click Add.
-
To save changes, click Apply > Confirm.
Remove Entitlements in Subscriptions
The remove entitlements function is used to disable the entitlements of an already existing feature in a subscription. These steps apply to non-metered features.
To remove entitlements, follow these steps:
-
Click Subscriptions page > Entitlements > Edit.
-
You are redirected to the Entitlements index page for the subscription. Click on the pencil icon of the entitlement you want to disable.
-
A pop-up appears. Turn off the Enable this entitlement toggle to disable the entitlements, and click Override.
-
Click Apply to disable the entitlements.
-
Click Confirm to save your changes.
When an item entitlement is disabled, you can't update the entitlement level value. To update the entitlement level value, enable the entitlement first.
Entitlements for Direct Subscription Charges
- Log in to Chargebee.
- Go to the Subscriptions page, then the Subscription Details page. Select a subscription.
- Click Add Charge, then select the charge you are adding.
- Configure the charge details.
- Click Add.
- The charges will be displayed on the Entitlements Card.
Add One-Time and Quick Charges
Using the Add One-Time Charges and Quick Charges feature, you can add multiple charges either at the customer or subscription level.
To add multiple charges:
- Log in to Chargebee.
- Go to the Customers or Subscriptions page, then select a customer or subscription.
- Click Add One-Time Charges and Quick Charges.
- Click Add Charge, then select the charge.
- Configure the charge details and click Add.
- Repeat steps 4 and 5 to add multiple charges.
- The charges will be displayed on the Entitlements Card.
To learn more about customer-level entitlements, refer to customer entitlements.
FAQ
1) Can I integrate entitlements with third-party billing applications to sync data directly?
Entitlements do not have a direct, native integration with third-party billing applications. However, you can use Chargebee's APIs and webhooks to create, retrieve, and sync entitlement data with external systems. Listen for the entitlement webhooks, and then call the List Subscription Entitlements API to refresh the data in the external system. For the list of webhooks and the steps, see Keep subscription entitlements in sync with your application.
2) How can I add entitlements to a subscription for a limited period?
Chargebee allows you to add entitlements of non-metered features to your subscriptions for a limited period. To add limited-period entitlements, click Chargebee > Subscriptions > select a subscription for which you need to add a limited-period entitlement > scroll down to the Entitlements section > click Add or Edit Entitlements > click + to add the feature to this subscription. If you want to add the entitlement permanently, select Forever. If you're going to set it for a limited time, select Until, and choose a date when you want the entitlement to expire. Click Add. To save changes, click Apply > Confirm.