Overview

Lumen separates what you sell (features) from how you measure it (events → metrics). You grant access by checking features, and you price using metrics that aggregate events you send from your app.

What this is

• Features: Booleans, numbers or strings that your code checks to decide access and limits.
• Events: Immutable usage signals your backend emits when users do something.
• Metrics: Computations over events (count, sum, unique, custom SQL) used for billing and entitlement-with-usage checks.

When to use this

• You need clear feature gates in code without coupling to plans.
• You want usage-based pricing, free allowances, or overage.
• You need analytics-grade metrics (e.g., unique users, filtered cohorts) to drive pricing or UI.

UI vs API

UI: One-click plan creation

You can use the Create Plan page to configure everything in one place: plan details, pricing (fixed, usage, or per-seat), features, and credit allowances.

• When you click Create, Lumen automatically:
  • Creates the plan and version
  • Creates the prices and links them to the plan
  • Creates the features and links them to the plan
  • Creates metrics for any usage-based features and links them to the features and the usage based price
  • Creates and links credit definitions with the renewal you choose (billing-cycle or monthly/yearly) and links them to the features and the usage based price
  • Enables pricing-table visibility and trial options if selected

This is the best way to get started with for a vast majority of pricing models. Best when you want speed, safe defaults, and consistent wiring without manual steps.

API: Step-by-step control

The API allows incredible flexibility and control over the pricing model but it comes at the cost of needing manual setup.

You would start by creating the plan and then manually creating the features, prices, metrics, and credits and then linking them to the plan. There's is a detailed guide on how to do this here.

Best when you require custom pricing components with odd cycles, mixed cycles, advanced SQL metrics, finely controllable credit definitions, overrides and precise migration controls. If you need help, please reach out to us at help@getlumen.dev.

Quick mental model

1. Create features you’ll gate on, like api-calls or premium-support.
2. Emit events from your product, e.g. api-call on every successful request.
3. Define metrics that compute billable quantities from those events.

Example mapping:

• “API calls per month” → metric: COUNT of events where event_name = 'api-call'.
• “AI tokens processed” → metric: SUM of eventValue on ai-token events.
• “Monthly active users” → metric: COUNT DISTINCT customer_id via an indexed SQL metric.

Next

• Go to Features to model what you gate.
• Then Events to send usage.
• Finally Metrics to compute values for billing and limits.

See also

• Design pricing: Plans & Pricing
• Resolve issues fast: Troubleshooting & Patterns