Features

Manage feature access and usage limits across plans

Overview

Features in FlexPrice define capabilities that can be included in plans and controlled through entitlements. They enable feature flagging, usage limits, and access control based on what customers have purchased.

Feature Types

FlexPrice supports three types of features, each serving different use cases:

Metered

Track quantitative usage with limits

Boolean

Simple on/off feature flags

Static

Fixed quota or allowance

Metered Features

Metered features track actual consumption and compare it against configured limits.

Metered Feature

{
  "id": "feat_api_calls",
  "name": "API Calls",
  "lookup_key": "api_calls",
  "type": "metered",
  "description": "Number of API requests per month",
  "meter_id": "meter_api_requests",
  "unit_singular": "call",
  "unit_plural": "calls",
  "alert_settings": {
    "critical": {
      "threshold": 90,
      "enabled": true
    },
    "info": {
      "threshold": 75,
      "enabled": true
    }
  },
  "metadata": {
    "category": "usage"
  }
}

Key Characteristics:

• Requires meter_id to link to usage tracking
• Supports alert thresholds (e.g., notify at 75% and 90% of limit)
• Units displayed in UI (“1,000 calls” vs “1,000 API Calls”)
• Usage resets based on billing period

Use Cases:

• API request limits
• Storage quotas
• Compute hours
• Email sends
• Team member seats (if metered)

Boolean Features

Simple on/off toggles for capabilities.

Boolean Feature

{
  "id": "feat_sso",
  "name": "Single Sign-On",
  "lookup_key": "sso",
  "type": "boolean",
  "description": "SAML/OAuth SSO integration",
  "metadata": {
    "category": "security",
    "enterprise_only": "true"
  }
}

Key Characteristics:

• No meter required
• No quantity tracking
• Binary access (enabled/disabled)

Use Cases:

• Premium feature access (SSO, advanced analytics)
• Integrations (Salesforce, Slack)
• Priority support
• Custom branding

Static Features

Fixed allowances that don’t track real-time usage.

Static Feature

{
  "id": "feat_team_size",
  "name": "Team Members",
  "lookup_key": "team_members",
  "type": "static",
  "description": "Maximum number of team members",
  "unit_singular": "member",
  "unit_plural": "members",
  "metadata": {
    "category": "capacity"
  }
}

Key Characteristics:

• No real-time tracking via meters
• Fixed quota defined in entitlement
• Manual enforcement (your application checks the limit)

Use Cases:

• Project limits
• Workspace counts
• Maximum team size
• Template libraries

Feature Structure

Core Fields

id · string · required

Unique identifier for the feature (max 50 characters)

name · string · required

Display name of the feature (max 255 characters)

lookup_key · string · required

Unique human-readable identifier for API lookups (max 255 characters)

type · enum · required

Feature type: metered, boolean, or static

description · text

Detailed description of what the feature provides

meter_id · string

ID of the meter tracking this feature’s usage (required for metered type)

unit_singular · string

Singular form of the unit (e.g., “call”, “GB”, “user”)

unit_plural · string

Plural form of the unit (e.g., “calls”, “GB”, “users”)

metadata · object

Custom key-value pairs for additional feature information

Alert Settings

For metered features, configure usage alerts:

Alert Configuration

{
  "alert_settings": {
    "critical": {
      "threshold": 90,
      "enabled": true
    },
    "info": {
      "threshold": 75,
      "enabled": true
    }
  }
}

alert_settings.critical.threshold · integer

Percentage of limit to trigger critical alert (0-100)

alert_settings.critical.enabled · boolean

Whether critical alerts are active

alert_settings.info.threshold · integer

Percentage of limit to trigger informational alert (0-100)

alert_settings.info.enabled · boolean

Whether info alerts are active

Alert thresholds trigger notifications when usage reaches the specified percentage. For example, with a 10,000 call limit and 75% threshold, an alert fires at 7,500 calls.

Features and Entitlements

Features define what exists. Entitlements define who has access and how much.

Feature Definition

{
  "id": "feat_storage",
  "name": "Cloud Storage",
  "lookup_key": "storage",
  "type": "metered",
  "meter_id": "meter_storage_gb",
  "unit_singular": "GB",
  "unit_plural": "GB"
}

Defines the “Cloud Storage” capability with metered tracking.

Plan Entitlements

Different plans grant different amounts:

Starter Plan:

{
  "feature_id": "feat_storage",
  "limit": 10,
  "has_unlimited": false
}

Professional Plan:

{
  "feature_id": "feat_storage",
  "limit": 100,
  "has_unlimited": false
}

Enterprise Plan:

{
  "feature_id": "feat_storage",
  "limit": null,
  "has_unlimited": true
}

Access Check

Your application checks entitlements:

Example Check

const entitlement = await flexprice.entitlements.check({
  customer_id: "cust_123",
  feature_lookup_key: "storage"
});

if (entitlement.has_access) {
  if (entitlement.has_unlimited) {
    // Unlimited storage
  } else {
    // Check: current_usage < limit
    const remaining = entitlement.limit - entitlement.current_usage;
    console.log(`${remaining} GB remaining`);
  }
} else {
  // Feature not available on their plan
}

Feature Gating Patterns

Hard Limits (Enforce)

Prevent actions when limit is reached.

const { has_access, current_usage, limit } = await checkEntitlement(
  customerId, 
  'api_calls'
);

if (!has_access || (limit && current_usage >= limit)) {
  throw new Error('API call limit exceeded. Please upgrade your plan.');
}

// Proceed with API call
await processRequest();

When to Use:

• Resource limits (storage, API calls)
• Security/compliance constraints
• Infrastructure capacity

Soft Limits (Warn)

Allow usage but notify the customer.

const { current_usage, limit } = await checkEntitlement(
  customerId,
  'team_members'
);

if (limit && current_usage >= limit * 0.9) {
  await sendNotification({
    type: 'warning',
    message: `You're at ${current_usage}/${limit} team members. Consider upgrading.`
  });
}

// Allow the action
await addTeamMember();

When to Use:

• Encouraging upgrades
• Non-critical limits
• Grace periods

Feature Toggle

Enable/disable functionality based on plan.

const { has_access } = await checkEntitlement(
  customerId,
  'advanced_analytics'
);

return {
  showAnalyticsDashboard: has_access,
  features: has_access ? ['reports', 'exports', 'custom_charts'] : []
};

When to Use:

• Premium features
• Optional integrations
• UI customization

Tiered Access

Different plans get different levels of the same feature.

const { limit, has_unlimited } = await checkEntitlement(
  customerId,
  'projects'
);

let maxProjects;
if (has_unlimited) {
  maxProjects = Infinity;
} else {
  maxProjects = limit || 3; // Default to 3 if not specified
}

if (currentProjectCount >= maxProjects) {
  return { error: 'Project limit reached', upgradeRequired: true };
}

When to Use:

• Scaling limits across plans
• Capacity-based pricing
• Freemium models

Alert Workflows

When usage crosses thresholds:

1. Usage Tracked

   Events flow to the meter linked to the feature:

   {
     "customer_id": "cust_123",
     "event_name": "api.request",
     "properties": {"endpoint": "/v1/data"}
   }
   
2. Threshold Check

   FlexPrice compares current usage to entitlement limit and alert thresholds.

3. Alert Generated

   When threshold is crossed, an alert event is created:

   {
     "type": "feature.usage.threshold",
     "severity": "info",
     "feature_id": "feat_api_calls",
     "customer_id": "cust_123",
     "current_usage": 7500,
     "limit": 10000,
     "threshold_percentage": 75
   }
   
4. Notification Sent

   Your application handles the alert (webhook, email, in-app notification).

Best Practices

Clear Naming

Use names that match your product UI:

• Good: “API Requests”, “Team Members”, “Storage”
• Avoid: “Feature 1”, “Limit A”, “Quota X”

Set Meaningful Units

Define singular and plural forms:

{
  "unit_singular": "project",
  "unit_plural": "projects"
}

Displays as “1 project” or “5 projects” in UI.

Use Metadata

Categorize and tag features:

{
  "metadata": {
    "category": "collaboration",
    "premium": "true",
    "launched": "2024-01"
  }
}

Configure Alerts Wisely

Set thresholds that give users time to act:

• Info: 75% (“heads up”)
• Critical: 90% (“take action soon”)
• Consider 95% or 100% for final warnings

Meter Requirement: Metered features MUST have a valid meter_id. The system will reject metered features without a linked meter.

Boolean Features: Don’t track usage or require meters. Simply check has_access in entitlements.

Example Scenarios

E-commerce Platform

{
  "features": [
    {
      "name": "Products",
      "lookup_key": "products",
      "type": "static",
      "unit_singular": "product",
      "unit_plural": "products"
    },
    {
      "name": "Monthly Orders",
      "lookup_key": "orders",
      "type": "metered",
      "meter_id": "meter_orders",
      "unit_singular": "order",
      "unit_plural": "orders",
      "alert_settings": {
        "critical": {"threshold": 90, "enabled": true}
      }
    },
    {
      "name": "Multi-Currency",
      "lookup_key": "multi_currency",
      "type": "boolean"
    }
  ]
}

Related Resources

Entitlements

How features are granted to customers

Meters

Track usage for metered features

Plans

Package features into sellable plans

Events

Send usage data for feature tracking