Why use Lumen?

Lumen is a billing system that makes it easy to build complex pricing plans for your SaaS product.

A Simple Example

Billing will be easy, right? Just charge a credit card.

Let's take an example: You're selling a SaaS product like ChatGPT to businesses. You want a fixed price per seat each month. You give out 100 monthly AI messages for the Premium models, 1000 monthly AI messages for the cheaper models and then, you want to charge any overage at some price - for example, $0.20 per message for premium models, $0.02 per message for the cheaper models.

To build this with Stripe, you will need to build your own entitlement system that can track real-time usage for each business seat. This will be quite complex - think about the edge cases like mid-cycle changes, refunds, prorations, taxes, etc. Building a realtime event system that can handle high-volume events and aggregate usage data before each user request is also a lot of work.

With Lumen, you can have this pricing model working in 5 minutes flat (including integrating it in your app). We handle all the complex stuff like realtime event ingestion and usage aggregation, credits, tax and invoices.

We can integrate with any payment provider of your choice - so if you're already using Stripe, you can keep using it with Lumen. Or, email us and we'll integrate with any payment provider you want!

Features, not plans

With Stripe, most developers implement plan-based checks scattered throughout their codebase:

if (plan === "pro") {
  // give access to expensive feature A here
}
if (plan === "plus" || plan === "pro") {
  // give access to cheaper feature B here
  // also give access to feature C
}

Consider this scenario: Your Chief Revenue Officer discovers that "advanced analytics" feature drives conversions and wants to move it to the free plan with a 7 day trial period. Now engineers must find and update every related conditional without breaking existing functionality, with the added complexity of figuring out how to implement this free trial feature.

With Lumen, your code stops checking for plan === "plus". Instead, it checks for features.

if (
  await isFeatureEntitled({ feature: "advanced-analytics", userId: user.id })
) {
  // give access
}

This small change decouples your code from your pricing and feature-access. You can easily change which plans get which features, change how many credits you're granting, change prices, grant over-ride access to some features to individual customers, all without touching code.

The Architectural Trap of Webhooks

Traditional payment processors force you to manage state.

You get a webhook when a subscription is created. You store the customerId and subscriptionId in your database. You get another webhook when a payment succeeds, and you update a status field. When a payment fails, you get another one.

Your application becomes a distributed system, constantly trying to keep its local state in sync with a remote service.

This is brittle. If you miss a webhook, your user's access might be incorrectly revoked, or they might not get access to a feature they paid for. Your database is now out of sync, and you have to manually reconcile it. Every time you want to change your pricing, you have to revisit this fragile logic.

With Lumen, there are no webhooks to manage and no state to sync. Lumen is the source of truth for who has access to what and how they should be billed for it. You ask our SDK at runtime. That's it.

// Is this user entitled to the 'pro-feature'?
const canAccess = await isFeatureEntitled({ feature: "advanced-analytics", userId: user.id })

// How many API calls has this user made this month?
const featuresUsage = await getUsage({ userId: "..." });
// returns usage for each feature along with limits based on credits the user has

This removes entire categories of bugs and radically simplifies your architecture. You don't need to build a state-management system just to get paid.

What Lumen Handles For You

• Flexible Pricing: Model anything. Fixed fees, per-seat, usage-based tiers, or combinations with different billing cycles. Your pricing model lives in Lumen, not in your code.
• Credits & Entitlements: Native support for usage credits and monetary discounts. Track entitlements and apply credits without building a separate ledger.
• Usage & Metering: We ingest high-volume events and handle the aggregation for you. Your app just needs to report events; we do the math.
• Versioned History: Every change to a plan or subscription is versioned. You get a complete, auditable history of everything, which makes debugging and compliance simple.

You no longer need to build and maintain:

• A webhook ingestion and state-syncing system.
• An event metering and aggregation pipeline.
• A credit ledger and proration calculator.
• Fragile if/else statements for plan logic scattered across your codebase.