Entitlements and billing should be the same system

There are a few questions that have plagued humanity forever:

• Does God exist?
• What’s the meaning of life?
• Is love real or merely a biochemical reaction in the brain?
• Which monetization features deserve their own micro-service?
• Is the tradeoff of separating billing and entitlements worth it?

I can’t speak to the former three, but today we’ll aim to answer the latter two. Today, we’ll share why we’ve built entitlements into our billing system (and it's available for all users now!).

But let’s start at the beginning. Why should you care about billing and entitlements? The tension between the two illustrates a general tension in architecture: When do we build a new microservice (risking sprawl) and when do we extend an existing one (risking complexity)?

To explore how we answered this question, let’s explain what we’re talking about.

What are entitlements and how do they work?

There are two ways companies can make features available in usage-based billing:

• Billable metrics: These are what users pay for based on some type of unit.
• Entitlements: These are features that come with a plan and can’t be purchased.

Technically, an entitlement is a feature flag: It either enables or disables features based on data about the user or organization (typically related to plan, usage or payment status).

Let’s take an example from Supabase:

In this case:

• MAUs are a billable metric because you can buy one MAU for $0.00325
• 7-day log retention is an entitlement. You can’t buy 8-day log retention.

You might be asking: What about those 100k included MAUs? Isn’t that an entitlement because it comes with the plan? From a psychological perspective, yes. From an engineering perspective, no.

To bill for this metric, the logic is relatively easy:

• IF the user is on the Pro plan, activate the events API to track MAU events. For MAU counts up to 100,000, bill $0. If total MAU count exceeds 100,000, bill $0.00325 per event. Finalize invoice at the end of the month.

This is called a billable metric with a free tier because you can buy more than your plan includes. If you got 100,000 MAUs and Supabase just stopped accepting new users, that’d be an entitlement.

Technically, there’s nothing stopping you from turning entitlements into billable metrics and vice-versa. You could charge for support by the email and shut down new MAUs after 100,000.

What’s an entitlement and what’s a billable metric is typically driven by product considerations. Obviously a database that arbitrarily stops accepting new users until the customer upgrades is horrible. Just as horrible as being charged by the support email.

So you need both entitlements and billing. But their relationship can be tense.

How to balance entitlements and billable metrics

Like in the micro-services vs. monolith holy war, you can view this in two different ways:

A billing system manages revenue. An entitlement system manages access. To the most pedantic engineers, this difference in use case already warrants separating the systems.

Additionally, most people want to touch billing as little as possible. But product/growth teams constantly want to update entitlements, plans, etc. If experimenting with plans means directly touching billing, that can feel dangerous because dependencies could create incorrect charges.

Entitlements also directly transform the user experience because they regulate access. This way, an error in a combined billing-entitlements system could directly affect UX. Keeping billing separate and only sending basics like user ID and which plan they’re on means lowering risk of compounding errors.

But this opinion comes from a time when pricing was easy. It assumes a lot of pre-AI economics. Billing information used to be relatively easy: You mainly charged fixed, regular fees and had zero gross margin worries.

AI is transforming this as we shift to more complex pricing models. Margins can go negative and new models require frequent changes to the billing system itself.

So here’s why we built entitlements into Lago:

We frequently see that AI features and products bring existing stacks to their knees. There’s a billing system (that’s often only built for simple subscriptions) and a payment provider that enable charging customers and a feature-flagging tool that enables entitlements.

Plus a whole lot of internal logic that somehow, kinda works and we all hope it doesn’t break because the engineer who built it left 5 months ago and nobody knows how to keep it running.

That’s how an attempt to reduce complexity by keeping things separated makes things more complex by creating dependencies.

The “keep it separate” point of view is also vastly worse when things break (and trust me, they will). If a customer runs into a limit that shouldn’t exist (or using a feature they’re not entitled to), it’s much harder to trace back where that came from.

It can also increase workloads when database entries and workflows aren’t perfectly mirrored. Suddenly, product needs to request changes in two systems.

These two systems also compound with all of the systems they in turn are integrated with. This means both internal APIs in the product and external systems like a CRM or ERP.

This is why we’ve built entitlements right into Lago.

Why entitlements should live in billing

First, Lago is used by both technical and non-technical users. This includes the engineers that build it and salespeople who build out custom plans and deals or product/growth who want to get an overview on data.

When the same systems includes both entitlements and billing, the overview gets much easier and data changed in one directly gets changed in the other.

It also makes it easier to build the complex plans many AI companies depend on to sell, without needing “duct tape code” that only exists to connect the two systems.

Finally, there’s a single place the data lives and to find out what a customer is paying, using and what they get access to.

Conclusion: Isn’t this just a monolith?

We’re not saying the ideal solution is a monolith where we bolt on feature after feature until it becomes impossible to disentangle. That’s just as undesirable as micro-service sprawl.

What we aim to build is a foundational system that contains connected, but decoupled systems (billing and entitlements), which still presents a unified interface and workflow to the user.

That’s why entitlements in Lago treat entitlements as distinct from billable metrics and can be attached to any plan object.

To summarize: Entitlements in Lago create a single, combined API and UI. This means the technical separation is invisible to the user, which creates the simplicity of a single system with the safety of separate services.

‍