Checking Subscription Entitlements And Providing Feature Access

Chargebee provides the feature resource to help you define various features offered as part of your product line. This tutorial explains how you can check if a user of your system is entitled to a feature and then provide them access to it. This is achieved by retrieving and checking the subscription_entitlement object. The subscription_entitlement object specifies the entitlement a specific subscription has towards a specific feature.

If you want more guides to help with other use cases for the Entitlements API, reach out to us at Chargebee Support.

Prerequisites

Start by ensuring that the following objects have been created in Chargebee:

• feature objects to model the features you offer your users.
• item_entitlements towards those features.

Implementation

Perform the following steps each time the user logs in and a session is created:

Based on your use case, the user in the diagram below could be a human being or even a device such as in IoT.

The following steps explain the sequence shown in the above diagram:

1. Log the user in and check their subscription.id.
   1. The user logs in and undergoes authorization and authentication with your application.
   2. Your application retrieves subscription.id of the user.
2. Retrieve subscription_entitlements.
   1. Your application attempts to retrieve the subscription_entitlements object from its cache.
   2. If there is a cache miss, retrieve subscription_entitlements from Chargebee and store it in the cache.

   curl  https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/subscription_entitlements \
     -G  \
     -u {site_api_key}:
   

   3. You will get a list of all entitlements to the subscription:

   {
     "list": [
       {
         "subscription_entitlement": {
           "id": "KyVnHhSBWlm1j2m7",
           "subscription_id": "JzDnHhSBWlm1j1n4",
           "feature_id": "salesforce-integration",
           "feature_name": "Salesforce integration",
           "value": "available",
           "name": "",
           "is_overridden": false
         }
       },
       {
         "subscription_entitlement": {
           "id": "KyVnHhSBWlm1j2m7",
           "subscription_id": "JzDnHhSBWlm1j1n4",
           "feature_id": "number_of_users",
           "feature_name": "Number of users",
           "value": "10",
           "name": "",
           "is_overridden": false
         }
       }
     ]
   }
   

3. Check subscription entitlements and allow/deny access to feature.
   1. Extract the JSON object corresponding to the feature_id from the list.
   2. Verify whether the user’s role and permissions allow them to access or modify this feature.
   3. Compare the consumed entitlement level of the feature with subscription_entitlements.value and allow/deny the user access to the feature:
      1. For feature.type switch, allow access if subscription_entitlements.value is true.
      2. For feature.type quantity or range, allow access when subscription_entitlements.value is either unlimited or more than the consumed entitlements for the feature.
      3. For feature.type custom, allow access based on your specific interpretation of subscription_entitlements.value.