Skip to main content
Features represent the capabilities you bundle with your products—things like “SSO enabled”, “Premium support”, or “100GB storage”. When customers subscribe to a plan, they automatically receive entitlements that grant access to these features.

​
How It Works

  1. Create features for your product (via Platform UI)
  2. Link features to prices within a plan
  3. Customers subscribe and entitlements are provisioned automatically
  4. Check entitlements via API to gate access in your application

​
Feature Types

Boolean

Simple on/off access. Either the customer has it or they don’t.Examples: SSO enabled, Premium support, API access

Static

Fixed capability with configuration values that define limits or quotas.Examples: 25 team seats, 100GB storage, 1000 API calls/month

Metered

Track usage quantities against the feature.
Coming soon

​
Creating Features

Features are created through the Platform UI.
1

Navigate to your product

Go to Products and select the product you want to add features to.
2

Open the Features tab

Click the Features tab to view and manage features for this product.
3

Create a new feature

Click New Feature and fill in the details:
  • Name: Display name shown in the UI (e.g., “AI Tokens”)
  • Key: Unique identifier used in API calls, lowercase with hyphens (e.g., ai-tokens)
  • Type: Boolean or Static
4

Save the feature

Click Save to create the feature. It’s now available to link to prices.
Use descriptive, consistent keys for your features. They’ll appear in API responses and your application code.

​
Linking Features to Prices

Once you have features, link them to prices within your plans. This determines what entitlements customers receive when they subscribe.
1

Navigate to a plan

Go to Products > Plans and select the plan you want to configure.
2

Edit a price

Select a price within the plan to edit its configuration.
3

Select a feature

Choose a feature from the dropdown to associate with this price.
4

Configure entitlement template (for Static features)

For Static features, define the configuration values that will be granted:
{
  "maxUsers": 25,
  "storageGB": 100
}
To add features to a plan without charging for them, create a fee with a price of 0. This lets you attach a feature for entitlement purposes while not billing the customer.

​
Automatic Entitlement Provisioning

When a customer subscribes to a plan, entitlements are automatically provisioned based on the features linked to that plan’s prices.
Subscription EventEntitlement Action
Subscription createdEntitlements provisioned automatically
Subscription terminatedEntitlements canceled
No manual intervention required—the system handles the lifecycle automatically.

​
Checking Entitlements via API

Use the API to check if a customer has access to specific features. This is how you gate functionality in your application.
API Reference: See the List Entitlements API endpoint for complete request and response schemas.

​
List Customer Entitlements

const axios = require('axios');

async function checkEntitlements(customerId) {
  const response = await axios.get(
    'https://api.paygentic.io/v1/entitlements',
    {
      params: {
        customerId: customerId
        // Optional filters:
        // featureKey: 'sso-access',
        // productId: 'prod_abc123'
      },
      headers: {
        'Authorization': 'Bearer sk_test_YOUR_API_KEY'
      }
    }
  );

  return response.data;
}

// Example: Check if customer has SSO access
const entitlements = await checkEntitlements('cus_abc123');
const hasSso = entitlements.data.some(
  e => e.featureKey === 'sso-access' && e.hasAccess
);

​
Response Format

{
  "object": "list",
  "data": [
    {
      "hasAccess": true,
      "featureKey": "sso-access",
      "featureType": "boolean",
      "config": null,
      "entitlementId": "ent_abc123",
      "productId": "prod_xyz789",
      "activeFrom": "2024-01-01T00:00:00Z",
      "activeTo": null,
      "status": "active"
    },
    {
      "hasAccess": true,
      "featureKey": "storage-quota",
      "featureType": "static",
      "config": {
        "limitGB": 500
      },
      "entitlementId": "ent_def456",
      "productId": "prod_xyz789",
      "activeFrom": "2024-01-01T00:00:00Z",
      "activeTo": null,
      "status": "active"
    }
  ]
}

​
Key Response Fields

FieldDescription
hasAccessWhether the customer currently has access to this feature
featureKeyThe unique identifier for the feature
featureTypeboolean or static
configFor static features, the configuration values (limits, quotas, etc.)
statusCurrent status: active, expired, or canceled

​
Use Cases

​
Feature Gating

Check hasAccess before enabling premium features in your application: 
const entitlements = await checkEntitlements(customerId);
const ssoEntitlement = entitlements.data.find(e => e.featureKey === 'sso-access');

if (ssoEntitlement?.hasAccess) {
  // Enable SSO login option
  showSsoButton();
} else {
  // Show upgrade prompt
  showUpgradePrompt('SSO is available on Professional plans and above');
}

​
Enforcing Limits

Read config values for static features to enforce limits: 
const entitlements = await checkEntitlements(customerId);
const storageEntitlement = entitlements.data.find(e => e.featureKey === 'storage-quota');

if (storageEntitlement?.hasAccess) {
  const limitGB = storageEntitlement.config.limitGB;
  const currentUsageGB = await getCurrentStorageUsage(customerId);

  if (currentUsageGB >= limitGB) {
    throw new Error(`Storage limit of ${limitGB}GB reached`);
  }
}

​
Subscription-Aware Access

Entitlements automatically update when subscriptions change—no need to track subscription status separately: 
// This works whether the customer upgraded, downgraded, or churned
const entitlements = await checkEntitlements(customerId);

// Build a feature map for your application
const features = {};
for (const e of entitlements.data) {
  features[e.featureKey] = {
    enabled: e.hasAccess,
    config: e.config
  };
}

​
Next Steps