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.

Note

If you'd like to request more of such guides to solve other use cases with the Entitlements API, contact us at [email protected]

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.

Tip
It is recommended that you cache the subscription_entitlement resource in your system to speed up the process of checking entitlements.

Implementation 

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

Note

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.
  2. The user logs in and undergoes authorization and authentication with your application.
  3. Your application retrieves subscription.id of the user.
  4. Retrieve subscription_entitlements.
  5. Your application attempts to retrieve the subscription_entitlements object from its cache.
  6. 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}:
    
  7. 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
            }
        }]
    }
    
  8. Check subscription entitlements and allow/deny access to feature.
  9. Extract the JSON object corresponding to the feature_id from the list.
  10. Verify whether the user's role and permissions allow them to access or modify this feature.
  11. 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.

Tip

  • It is recommended to define a time-to-live (TTL) attribute against subscription_entitlement cache entries so that they may get refreshed periodically.
  • If you have a more real-time use case, it is better to listen to webhooks and invalidate the associated cache entries.