How Lumen Fits Together

Lumen separates what you sell from how you charge for it. Your code checks features, not plans. This makes pricing changes trivial.

The Core Model

Features - What customers can access (API calls, premium support, etc.)

Plans - Bundles of features that form your product tiers

Prices - How much a plan costs ($29/month, €290/year, etc.)

Subscriptions - The link between a customer, their features, and what they pay

Features

Features are what you sell. Three types:

Boolean: premium-support (yes/no)
Numeric: api-calls (10,000 limit)
String: region ("us-east-1")

Your code should only check features: isFeatureEntitled('api-access'), never user.plan === 'pro'.

Plans

Plans bundle features. They're templates, not the source of truth.

One plan can have multiple prices:

Professional Plan → $29/month, $290/year, €25/month

Plans are versioned. Change a plan, existing subscriptions keep their old version until you migrate them.

Subscriptions

This is where it gets important. A subscription links a customer to features and a price.

When created, the plan's features are copied into the subscription. The subscription becomes the source of truth. Entitlement checks read from subscription features, not plan features.

You can override any subscription's features without touching the plan. Two customers on the "same plan" can have completely different features.

Example: Customer A gets 10,000 API calls (plan default). You override Customer B to 50,000 calls. Customer A is unaffected.

Usage Tracking

Events track what customers do:

sendEvent({ name: 'api-call', userId: 'user_123' });

Metrics aggregate events into billable quantities:

Count API calls this month
Sum bytes processed
Unique active users

Entitlements

When you check isFeatureEntitled('api-calls'):

Read the feature value from the customer's subscription
If it's numeric, compute current usage in the billing window
If there's an active credit for this feature, use the credit amount as the limit
Return: usage < limit

Credits can override subscription limits. A customer with 1,000 API calls in their plan but 5,000 in credits gets 5,000.

Credits

Two parts: definitions (templates) and grants (what customers have).

Usage credits provide allowances: "500 free API calls/month" Monetary credits reduce invoices: "$10 off"

Credits can renew automatically (monthly refill) or expire after a set time. They're processed by background jobs.

When to Use What

UI: Standard plans, simple features, monthly/annual pricing API: Complex pricing, custom metrics, enterprise overrides, bulk operations

The UI covers 80% of use cases. The API handles the complex 20%.

Next Steps

Features, Metrics & Events → Model what you sell
Plans & Pricing → Design pricing structure
Entitlements → Control feature access
Credits → Add allowances and trials