Create Feature

Use when defining a new feature or capability to gate or meter (e.g. feature flags or usage-based limits). Ideal for boolean or usage features.

POST /v1/features

cURL - Boolean feature

curl -X POST "https://api.flexprice.io/v1/features" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Analytics",
    "lookup_key": "advanced_analytics",
    "type": "BOOLEAN",
    "description": "Access to advanced analytics dashboard"
  }'

201

{
  "id": "feat_abc123",
  "name": "API Calls",
  "lookup_key": "api_calls",
  "type": "METERED",
  "description": "REST API access with usage tracking",
  "meter_id": "meter_xyz789",
  "unit_singular": "API call",
  "unit_plural": "API calls",
  "metadata": {},
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Request Body

name · string · required

Human-readable name for the feature (e.g., “API Access”, “Advanced Analytics”)

lookup_key · string

Unique identifier for API lookups (e.g., “api_access”, “advanced_analytics”)

Must be unique within the environment. Used for programmatic access.

type · string · required

Type of feature

Values:

• BOOLEAN: Simple on/off feature flag
• METERED: Usage-based feature with consumption tracking
• STATIC: Feature with a fixed configuration value

description · string

Detailed description of what this feature provides

meter_id · string

ID of an existing meter to use for METERED features

Either meter_id or meter must be provided for METERED features.

meter · object

Meter configuration for METERED features (alternative to meter_id)

Show Meter object

name · string · required

Name of the meter

event_type · string · required

Event type to track (e.g., “api_call”, “storage_gb”)

aggregation · string · required

How to aggregate usage

Values: SUM, COUNT, MAX, UNIQUE_COUNT

field · string

Field to aggregate (required for SUM and MAX)

unit_singular · string

Singular unit name (e.g., “API call”, “GB”)

Both unit_singular and unit_plural must be provided together.

unit_plural · string

Plural unit name (e.g., “API calls”, “GBs”)

Both unit_singular and unit_plural must be provided together.

alert_settings · object

Alert configuration for usage thresholds

Show Alert settings object

alert_enabled · boolean · default: "false"

Enable usage alerts

threshold_type · string

Type of threshold

Values: PERCENTAGE, ABSOLUTE

threshold_value · string

Threshold value that triggers alerts

metadata · object

Custom metadata as key-value pairs

Response

id · string

Unique identifier for the feature

name · string

Name of the feature

lookup_key · string

Lookup key for programmatic access

type · string

Feature type (BOOLEAN, METERED, or STATIC)

description · string

Feature description

meter_id · string

ID of the associated meter (for METERED features)

meter · object

Full meter object (if expanded)

unit_singular · string

Singular unit name

unit_plural · string

Plural unit name

alert_settings · object

Alert configuration

metadata · object

Custom metadata

created_at · string

Timestamp when feature was created

updated_at · string

Timestamp when feature was last updated

cURL - Boolean feature

curl -X POST "https://api.flexprice.io/v1/features" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Analytics",
    "lookup_key": "advanced_analytics",
    "type": "BOOLEAN",
    "description": "Access to advanced analytics dashboard"
  }'

201

{
  "id": "feat_abc123",
  "name": "API Calls",
  "lookup_key": "api_calls",
  "type": "METERED",
  "description": "REST API access with usage tracking",
  "meter_id": "meter_xyz789",
  "unit_singular": "API call",
  "unit_plural": "API calls",
  "metadata": {},
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Feature Types Explained

BOOLEAN

Simple on/off feature flags. Used for access control without usage tracking.

Examples:

• Premium support
• Advanced analytics
• Custom branding

METERED

Usage-based features that track consumption. Requires a meter for tracking.

Examples:

• API calls
• Storage (GB)
• Monthly active users

STATIC

Features with fixed configuration values (e.g., “5 team members”, “10GB storage”).

Examples:

• User seats
• Storage limits
• Project count

Creating Features with Meters

For METERED features, you have two options:

Option 1: Use Existing Meter

Reference a meter you’ve already created:

{
  "name": "API Calls",
  "type": "METERED",
  "meter_id": "meter_xyz789"
}

Option 2: Create Meter Inline

Define the meter configuration in the same request:

{
  "name": "API Calls",
  "type": "METERED",
  "meter": {
    "name": "API Call Counter",
    "event_type": "api_call",
    "aggregation": "COUNT"
  }
}

FlexPrice will create the meter automatically.

After Creating a Feature

Once you’ve created a feature, you can:

1. Add to plans: Include the feature in your plan entitlements
2. Check access: Use the Check Access endpoint to gate features
3. Track usage: Send events to meter usage for METERED features
4. Set limits: Configure usage limits via entitlements