This technical deep-dive was initially published on the Stigg blog.

What are entitlements? Why should engineering teams care? And how are they different from feature flags or authorization tools? Our CTO Anton takes you into a technical deep dive into entitlements for SaaS monetization.

How many times did you change something in your pricing?

If you’ve been around SaaS for a while, you know how dynamic this landscape is, forcing companies to continuously update their pricing and packaging to stay competitive.

Yet, every change entails a corresponding change in the codebase to accommodate the new packaging behavior, inherently becoming more complex and time-consuming than any engineering team appreciates.

Tight coupling between pricing models and application logic can create a significant overhead which usually means the pricing model won’t be changed often… and it might sound ridiculous, but many organizations ignore this problem and continue to suffer from an outdated and anchored pricing model because of bad software design choices in the early days of the company.

This article introduces entitlements, an elegant solution to a complex problem in software monetization, and what engineering teams need to know to utilize it effectively.

So, what are entitlements?

By focusing on features instead of pricing concepts, we can decouple the price model from the application logic. The concept of Entitlements encapsulates the feature access settings under various product variants (aka Pricing Plans or Packages), bridging the gap between how a product is sold and how it behaves for a variant.

In essence, entitlements are a set of permissions defining what a customer (paying or non-paying) can do with your software application. For example, an entitlement can grant the customer access to the “Audit logs” feature or limit their account to “5 seats” within a given plan.

In essence, entitlements are a set of permissions defining what a customer (paying or non-paying) can do with your software application.

Entitlements provide a clean separation of concerns, effectively streamlining the process of updating product features in response to changes in the pricing model.

The 3 types of entitlements and how to control access using entitlement checks

Entitlement checks are vital to accurately control and monitor the access and usage of features by customers. They ensure that customers are granted access to the features they’ve paid for and help prevent overuse or misuse of resources.

To have some common ground on how are the checks are evaluated, lets present an example of a basic entitlements data structure granted to a customer:

Link to code

These are the 3 most common types of entitlements in SaaS and how entitlement checks work for each of them:

Feature gates

Sometimes referred to as binary flags, these types of entitlements control whether a customer has access to a specific feature or not. For instance, a customer on a free plan might not have access to advanced analytics, but upgrading to a paid plan will enable this feature. These binary flags simply gate the feature—either the customer has access, or they don't.

Feature access is controlled by evaluating a condition at runtime based on the customer and feature identifiers. This check verifies whether the customer is entitled to access the particular feature or not.

Link to code

Configuration

This type of entitlement changes the behavior of a feature within the application, depending on the package or plan that a customer is on. For instance, a customer on a free plan of an observability tool might have the data retention policy set to 3 days, while a customer on a paid plan might have a longer retention of 14 days. The entitlement does not just control access, but also how the feature behaves within the application.

For configuration entitlements, the check doesn't just involve whether or not the feature is present but also retrieves a configuration value that drives application behavior.

Link to code

Soft/Hard limits

These entitlements cap the metered usage of certain features. In case of hard limits, access is fully cut off, once the limit is reached. For example, a customer has access to 5 seats. Once they reach 5 seats, they can’t invite more users. In case of soft limits, customers are alerted or throttled once they reach a certain usage level. For example, a customer may be limited to 1000 API calls per day under a free plan. Once the customer crosses the limit a "Maximum capacity reached" email is automatically sent, and a significantly lower API rate limit (or a grace period) is applied before the API starts rejecting new data.

In the case of metered entitlements that have soft or hard limits, these checks are performed against the expected usage (= current usage + new usage) in a per-request context. For hard limit checks, it’s crucial to prevent overages, so real-time data is essential for accuracy.

Link to code

For soft limit checks, where preventing an overage is less important, there’s some tolerance for eventual consistency. This means you can compare against cached or slightly stale usage, offering a balance between system performance and accurate usage tracking.

What entitlements are not

To fully understand what entitlements are, let’s cover some misconceptions about them as well.

Firstly, entitlements are not a customer setting. Entitlements are typically part of a contractual agreement between you and your customer, i.e. the plan the customer chose. Customer settings are individual configurations a customer can make within their account. For example, a customer pays for 1GB of log data per day. One of their applications in their development environment is spammy. The customer setting allows them to reduce the log data for this specific environment to 256mb, while the account is still entitled to 1GB in total.

Secondly, entitlements are not synonymous with plans, e.g. "Basic", "Pro", and "Enterprise". Entitlements are, at their core, marketable features. Different pricing plans may grant access to these features with various configurations, but an entitlement does not inherently represent a particular product level.

Why should you care about entitlements?

Managing pricing changes at the code level, without appropriate abstraction mechanisms, can quickly devolve into a tangled mess, resulting in more complexities than anticipated.

With entitlements, you can cleanly decouple the pricing model from the application logic, enabling swifter and smoother changes to your offerings. Any packaging change will take a fraction of the time you’d spend with hardcoded checks.

Besides taking much less of your time, you will make your organization that much more flexible in the way they go to market. You can introduce new features or tweak existing ones without having to overhaul the entire system. You’ll be able to quickly adapt to changes in the market, customer needs, or business strategies. This agility not only gives you a competitive edge but also makes for a better user experience as you can tailor your offerings to better suit your customers' needs.

On top of that, entitlements enable GTM teams to A/B test and experiment with pricing & packaging, without talking to developers at all. As outlined at the beginning of the article, SaaS pricing & packaging has to change regularly to keep up with the market dynamics. As an abstraction on top of your codebase, those changes will no longer require you to write code.

As an abstraction on top of your codebase, those changes will no longer require you to write code.

Adopting entitlements can save you tons of development hours, fewer bugs, and increase your chances of success in a rapidly changing market environment.

Fusing entitlements and metering

Metering becomes crucial, once your pricing model includes configuration or soft/hard limit entitlements. Say you limit your customers by the number of users they can add to their team, the amount of storage space they get access to, or the number of API calls they can make within a certain timeframe. Without measuring a customer’s usage of an entitlement, you won’t be able to enforce limits in the entitlement service, and the enforcement will have to leak into the application code. For example, a customer’s plan includes 5 seats. Without metering, you won’t know how many seats they actually use. Your customer could invite 30 other users, without being limited - or ever having a reason to upgrade.

Without measuring a customer’s usage of an entitlement, you won’t be able to enforce limits in the entitlement service, and the enforcement will have to leak into the application code.
‍
Metering software is designed to calculate feature usage, based on raw measurements that are often stored in an append-only system. This way, it is possible to maintain a historical record and allows querying for historical usage between different timeframes.

If you don't have a metering solution in place, you'll need to calculate the usage yourself. For simple counting, this is fairly straightforward – you just query your database to figure out how many instances of a feature or resource exist and compare it with the limit set by the entitlement.

However, when your usage is interval-based (such as a limit on API calls per month), it becomes more tricky. You need to design a system that can aggregate usage data for every passing interval, and that can correctly reset or roll-over counts when the interval ends.

For example, to support the entitlement, you’ll need to track and count the number of API calls:

Link to code

Hard stops

For entitlements with hard limits, once the limit is reached, access to the feature must be revoked to prevent any overuse. This is especially relevant for free plans. Hard stops also introduce perfect upsell opportunities, whether you support a self-service or sales-led model. For self-service products, present a paywall for your customer to allow them to upgrade and overcome the limit they’ve just experienced. For sales-led products, you can trigger a notification to your sales team to reach out to their customer.

Optimizing plans for success

Metering isn't just about enforcing entitlements. It's also a powerful analytical tool. By analyzing usage patterns, you can gain insights into how different features or resources are being used. This can inform decisions about how to optimize entitlement limits for future pricing packages and enables modern ways to go to market, such as hybrid pricing (i.e. combining fixed costs with limits and variable costs into a new pricing model).

Pro Tip: When talking about optimizing pricing plans, GTM teams will need a way to experiment with different versions of a plan. A good entitlement service should allow changing the upsell interface (e.g. paywalls or trial banners) dynamically to easily accommodate those experiments without additional coding.

Entitlements vs Billing

Billing software has a very specific role in managing financial transactions, invoicing, payment scheduling, and processing. Simply put, they handle everything when a customer swipes their credit card. In pricing & packaging, especially in self-service products, a lot is happening before and after that swipe, though. Many times, users first access your product through a free plan or trial period. Complex upgrade & downgrade flows require very smooth controls over who has access to what feature.

The key distinction between the two systems is that while billing software is focused on the commercial aspect, entitlements are all about provisioning and access control.

The key distinction between the two systems is that while billing software is focused on the commercial aspect, entitlements are all about provisioning and access control.

Why does your entitlement service have to be separated from your billing?

Bridging between application and billing
An entitlement service can be seen as a bridge between your application behavior and your billing process, and can become the source of truth for both pricing and packaging. Besides acting as an “anti-corruption layer” to shield potential integration errors with the billing software, it also provides a fail-safe layer in case the billing system is unreachable. If the need rises, this can allow you to switch between billing solutions in the future easier with much less coupling.

Dealing with legacy plans
Billing systems typically do not handle the concept of "grandfathering" (i.e. allowing legacy customers to stay on their plan, while updating the plan for new customers), or gradually transitioning customers from legacy plans to the new ones (e.g. when you add a new feature to an existing plan). There is also no native support for scheduling migrations of customer segments, so moving e.g. your legacy customers to the new plan at the end of their billing period will be pretty hard doing it, involving custom scripts and programmatically scheduling the transition. Entitlement services can automate this process, reducing the manual effort and ensuring a smoother transition for customers.

Centralized entitlement management
The main benefit of an entitlement service is that it allows you to manage each feature's business logic centrally. It's an independent system that decides who has access to what based on the user's subscription status. Billing software, on the other hand, isn't designed to carry out these checks or grant access to features. It's solely concerned with financial transactions.

Scalability and low latency
Entitlement checks are crucial for ensuring that applications operate reliably. These checks need to be made quickly and efficiently, which requires a system designed with low latency and scalability in mind. Billing systems typically don't offer this kind of performance because they delegate these concerns to the integrating system.

Flexible access management
An entitlement service allows for a much greater level of flexibility when it comes to managing user access. It can handle multiple sources of access rights, such as subscription plans, add-ons, and ad-hoc features (like promotions) granted to a customer. Billing systems are far more limited, as they’re focused on pricing and payment, not on deciding who gets access to what.

Decoupling pricing and access control
By separating entitlements from billing, you can decouple pricing from access control. With this separation, you can give users access to features independently of their billing status, offering more flexibility and control for use-cases like free & reverse trials, and customisations for enterprise customers.

Enforcing plan immutability
Billing systems usually don’t have safeguards to control changes of an existing plan. If one of your team members makes a change unintentionally, this will affect all your existing customers immediately. An entitlement service ensures that plan details are immutable, providing peace of mind for both operators and customers by preventing unexpected changes.

Development, Staging and Production environments
Billing systems often lack support for different environments or the development release lifecycle. For changes in your pricing model, whether you add or remove a feature, update the price or overhaul your entire model, you’ll probably want to build in development, test in staging, and only then move to production. Billing systems offer limited support for change management, delegating the tedious tasks of seeding data and syncing it between multiple development accounts to you. An entitlement service should support multiple environments and allow automatically promoting changes between different development, staging, and production in order to prevent potential drift.

In Part 2 of this technical deep-dive

...we're going to discuss different approaches to gating feature access for your end users. We're taking a closer look at authorization, feature flags, and plan identifiers, how to gate features with each of these approaches and the downsides you need to be aware of, before choosing any of these methods. Check out the top shortcomings we've identified here.

In Part 3 of this technical deep-dive

...we're sharing a curated list of best practices when working with entitlements. We've made it our company's mission to solve this complex issue for engineering teams and have learned a lot building Stigg. Whether you decide to look for a solution or build a service yourself, this list will help you make informed decisions. Check out our best practices here.

To wrap up

Operating in highly dynamic markets, SaaS companies have much less chances of success when compromising on rigid pricing models managed in the codebase.

Entitlements are the base for a truly flexible taxonomy and speed in go to market, allowing developers to quickly build and update pricing and giving GTM teams the opportunity to experiment with pricing & packaging, without code.

We made it our mission at Stigg to solve entitlements for SaaS. Our API gives you a flexible and scalable infrastructure, including metering, built-in experiments, a bunch of snap-in widgets, and native billing integrations, out of the box, and provides the automation to orchestrate everything about your pricing & packaging. If you consider buying over building, check out our Free plan. You can use one of our sandboxes to see all functionalities of Stigg.