Entitlement Checks

Stigg supports three types of feature entitlements: boolean (on/off), numeric (configuration values), and metered (usage-tracked with limits).

Generic entitlement check (recommended)

A unified method to check any type of feature entitlement. It automatically returns the appropriate entitlement type based on the feature configuration. You provide the customer ID and feature ID. Optionally, pass a resource ID for multi-subscription products, or a requested usage amount to proactively check if additional usage would be allowed (metered features only).

const entitlement = await stiggClient.getEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-demo-01',
  resourceId: 'resource-01', // optional, pass it to get entitlement of specific resource
});

if (entitlement.hasAccess) {
  // Customer has access to the feature
} else {
  // Access denied
  console.log('Access denied reason:', entitlement.accessDeniedReason);
}

// Entitlement contains the specific entitlement details
// based on feature type (boolean, numeric, or metered)
switch (entitlement.type) {
  case "NUMERIC":
    console.log('Numeric value:', entitlement.value);
    break;
  case "METERED":
    console.log('Usage limit:', entitlement.usageLimit);
    console.log('Current usage:', entitlement.currentUsage);
    break;
  case "BOOLEAN":
    break;
}

Show Result - boolean feature

{
  "isFallback": false,
  "hasAccess": true,
  "entitlement": {
    "type": "BOOLEAN",
    "feature": {
        "id": "feature-demo-01",
        "featureType": "Boolean",
        "meterType": "None",
        "isMetered": false
    }
  }
}

Show Result - numeric feature

{
  "isFallback": false,
  "hasAccess": true,
  "entitlement": {
    "type": "NUMERIC",
    "feature": {
      "id": "feature-demo-02",
      "featureType": "Numeric",
      "units": "request",
      "unitsPlural": "requests",
      "isMetered": false
    },
    "value": 100,
    "isUnlimited": false
  }
}

Show Result - metered feature

{
  "isFallback": false,
  "hasAccess": true,
  "entitlement": {
    "type": "METERED",
    "feature": {
      "id": "feature-demo-03",
      "featureType": "Numeric",
      "meterType": "Incremental",
      "units": "request",
      "unitsPlural": "requests",
      "isMetered": true
    },
    "usageLimit": 2,
    "isUnlimited": false,
    "currentUsage": 0,
    "resetPeriod": "MONTH"
  }
}

Boolean entitlement check

Check whether a customer has access to a boolean (on/off) feature.

const entitlement = await stiggClient.getBooleanEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-demo-01',
  resourceId: 'resource-01',      // optional
});

if (entitlement.hasAccess) {
  // customer has access to the feature
} else {
  // access denied
}

Numeric entitlement check

Retrieve the numeric value configured for a feature (e.g., max file size, API rate limit).

const entitlement = await stiggClient.getNumericEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-demo-02',
  resourceId: 'resource-01',      // optional
});

if (entitlement.hasAccess) {
  console.log(entitlement.value);
}

Metered entitlement check

Check whether a customer’s usage of a metered feature is within the allowed quota. You can optionally provide a requested usage amount to proactively verify if a specific amount of additional usage would be allowed before performing the action.

const entitlement = await stiggClient.getMeteredEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-demo-03',
  resourceId: 'resource-01',      // optional
  options: {
    requestedUsage: 10             // optional, proactively check usage
  },
});

if (entitlement.hasAccess) {
  // has access and the requested usage is within the allowed quota
} else {
  // the customer has exceeded his quota for this feature
}

Getting all entitlements

Retrieve all entitlements for a customer (or a specific resource), returning the full list of features they have access to along with usage limits and current usage.

const entitlementsState = await stiggClient.getEntitlementsState(
  'customer-demo-01',
  'resource-01', // optional
);

entitlementsState.entitlements.forEach((entitlement) => {
  console.log(JSON.stringify(entitlement));
});