Lumen Documentation

Features describe what your customers can access or use. Your code checks features by slug, not plans, so pricing and packaging changes don’t require code changes.

What a feature represents

Boolean — an on/off capability like premium-support or advanced-analytics
Numeric (usage-based) — a capability that consumes credits, e.g. api-calls, storage-gb
String — a configuration value like region or support-tier

Two key principles guide how features work at runtime:

Features are copied onto the subscription at creation time and can be overridden per customer later
For numeric features, credits provide the actual allowance; metrics compute usage from your events

The usage-based model (numeric features + credits)

Numeric features don’t store limits directly. Instead:

The feature is marked as "usage_based"
A metric tells Lumen how to measure usage (e.g., count api-call events)
Credits define how much is included (and optionally overage if tied to a price)

At entitlement time, Lumen compares current usage (from the metric) against the customer’s active credits and returns whether they’re entitled and how many credits remain.

Set up: UI fast path

Use the Create Plan page to model usage-based features quickly. Add a feature, specify whether it’s usage-based, optionally add per‑unit pricing, and save. The UI will:

Create the feature and attach it to the plan
Create the metric for your usage event (when usage-based)
Create credit definitions, with either billing‑cycle renewals or RRULE renewals
Link credits to the feature and, when pricing exists, to the usage component

This path is ideal for standard plans and common usage patterns.

Set up: API building blocks (minimal shapes)

Sometimes you’ll want to create things manually for custom behavior. The general flow is:

Create a numeric feature with featureValue: "usage_based"
Create a metric that computes usage (simple COUNT/SUM or SQL metric)
Create a credit definition linked to the feature (and to a price component if you want overage)

Example shapes (trimmed):

{
  "feature": {
    "slug": "api-calls",
    "displayName": "API calls",
    "featureValue": "usage_based"
  },
  "metric": {
    "name": "API calls (30d)",
    "queryType": "simple",
    "aggregationType": "COUNT",
    "eventName": "api-call",
    "valueType": "NUMERIC"
  },
  "creditDefinition": {
    "scope": "plan",
    "applicationType": "usage",
    "featureSlug": "api-calls",
    "defaultAmount": 10000,
    "renewOnBilling": true
  }
}

That’s all you need for the core loop: entitlement checks compare usage (from the metric) against allowance (from credits).

Using features in your app

Feature checks should gate actions, and successful actions should emit events for usage metrics.

Minimal flow (pseudocode):

// 1) Check entitlement
const entitlement = await fetch(`/v1/entitlements/${customerId}/feature/api-calls`).then(r => r.json());
if (!entitlement.entitled) {
  return upgradePrompt();
}

// 2) Do the thing (the API call, file upload, etc.)
await performBusinessAction();

// 3) Emit usage event after success
await sendEvent({ eventName: 'api-call', customerId, eventValue: 1, idempotencyKey });

Guidelines:

Emit events only after success and reuse the same idempotency key on retries
Keep event properties you’ll want to filter on later (endpoint, region, etc.)
Don’t check plans in code; always check features by slug

Common patterns

Naming: Use stable, lowercase slugs with hyphens: api-calls, ai-tokens, user-login. Keep feature names product-focused, not plan-focused.
Free allowance + overage: Link credits to a usage price component. Once credits are exhausted, overage is billed automatically.
Hard limit (no overage): Create usage credits without linking to a price component. After credits are consumed, deny access until renewal or more credits are granted.
Trials: Use the Create Plan page to add trial credit allowances for usage-based features; customers get temporary credits without enabling overage.
Seat features: Use per‑unit pricing with a seat-count metric (the UI can scaffold this); pair with credits only if you need an included seat allowance.

Evolving features safely

Renaming a feature slug cascades the change to plan and subscription feature rows
Overrides let you customize a single customer’s feature value without touching the plan
When you version a plan, subscriptions keep their current features until migrated

Troubleshooting

No usage showing up? Ensure the metric’s eventName matches the events you send
Limits not respected? Confirm the feature is usage_based and credits exist for that feature
Unexpected overage? Check whether the credit definition is linked to a price component

Features