Moving one feature from a plan to an add-on should cost the pricing team an afternoon. It becomes an engineering ticket when the product decides access with a line like if (account.plan === "team"). That line is a pricing decision stored in a file the pricing team can’t edit.
It looks harmless when there are two plans. Then Team gets renamed or split in two, and somebody has to grep the codebase for a string. Old customers stay on the old plan, so the old checks can’t be deleted either. A year in, the feature gate is a pile of conditions that records every pricing meeting the company has held.
Usage-based and hybrid pricing made this worse, because “what plan are they on” no longer tells you much. The answer the product needs is narrower: may this customer use this feature, and up to what limit.
So I’d put one table between billing and the product and make both sides talk only to it.
Billing writes grants, the product reads answers
The table holds grants. A grant says a customer may use a feature, optionally up to a limit, from one time until another, and it records where that permission came from.
Two things write grants. Billing events do: a subscription starts, changes or ends, and a small grant writer looks up the plan in a catalog that maps each plan to its features and limits, then writes one row per feature. Manual overrides do too: a sales rep gives a trial, support extends a limit for a month. Those go through the same writer and land in the same table with a different source.
Two things read. The product calls a check API and gets one answer per customer and feature. The CRM account panel reads the same rows, so a rep looking at the account sees what the customer can use and where each permission came from.
The plan catalog is the only place a plan name means anything. Product code asks about export_api, never about Team.
The grants table and its two statements
create table entitlement_grants (
grant_id bigint generated always as identity primary key,
customer_id text not null,
feature_key text not null,
limit_value bigint, -- null means on, with no limit
source text not null
check (source in ('plan', 'addon', 'trial', 'override')),
source_ref text not null, -- billing item + start date, opportunity, ticket
valid_from timestamptz not null default now(),
valid_to timestamptz, -- null means until revoked
created_at timestamptz not null default now(),
check (valid_to is null or valid_to > valid_from),
unique (customer_id, feature_key, source, source_ref)
);
create index entitlement_grants_lookup
on entitlement_grants (customer_id, feature_key, valid_to);
-- Grant writer: safe to replay the same billing event twice.
insert into entitlement_grants
(customer_id, feature_key, limit_value, source, source_ref, valid_from, valid_to)
values ($1, $2, $3, $4, $5, $6, $7)
on conflict (customer_id, feature_key, source, source_ref)
do update set limit_value = excluded.limit_value,
valid_to = excluded.valid_to;
-- Resolve: the winning grant per feature for one customer, right now.
select distinct on (feature_key)
feature_key, limit_value, source, source_ref, valid_to
from entitlement_grants
where customer_id = $1
and valid_from <= now()
and (valid_to is null or valid_to > now())
order by feature_key,
limit_value desc nulls first,
valid_to desc nulls first;
No row means no access. Several live rows for the same feature means the most generous one wins: no limit beats any number, and a bigger number beats a smaller one.
I prefer that rule to source priorities like “override beats plan”. With priorities, a concession written in March can quietly cap a customer who upgrades in May. With most-generous-wins, a grant can only ever add. If you need to take something away, for abuse or non-payment, that’s a block, and I’d keep blocks in their own table where nobody mistakes them for pricing.
Rows are never deleted. The writer ends a grant by setting valid_to, which leaves a history that can answer “why did they have export in February” with one query.
That only holds if source_ref names one version of the thing sold. Some billing systems keep the same subscription item id when the plan under it changes, and then the upsert would overwrite the old row instead of adding a new one. If yours does, add the date the change took effect to source_ref. The price id alone isn’t enough, because a customer who goes Team, Scale, Team lands on the same item and price twice.
Fenwick Co-op’s three rows
Sorrel Analytics is invented, and so is its customer, Fenwick Co-op. Sorrel sells a Team plan with 5 dashboards and 10 seats, and a Scale plan with 25 dashboards, 50 seats and the export API. Fenwick is on Team. A rep wants the deal to grow, so she grants a 60-day trial of the export API from the CRM.
| feature_key | limit_value | source | source_ref | valid_to |
|---|---|---|---|---|
| dashboards | 5 | plan | si_team_01 | null |
| seats | 10 | plan | si_team_01 | null |
| export_api | null | trial | opp_4417 | day 60 |
On day 12, Fenwick tries to create a sixth dashboard. The check for dashboards returns limit 5 from the plan grant, and the gate compares that to the current count and says no. The same day their script calls the export endpoint. The check for export_api returns allowed, source trial, expiring day 60, and the product can use that expiry to show a banner.
On day 61 the query’s time filter drops the trial row. Nobody ran a cleanup job and nobody edited a flag. The check returns nothing for export_api, and nothing means no.
An upgrade, then a downgrade
Say Fenwick upgrades to Scale on day 30. The billing event reaches the writer, which closes the two Team rows and writes three Scale rows, including export_api with source plan. Now two live grants cover export. The plan grant wins because it has no end date, and the trial expiring on day 60 changes nothing.
On day 45 they downgrade back to Team. The Scale rows close and fresh Team rows open, under a new source_ref, so the closed ones stay as history. dashboards returns 5 again. export_api still returns allowed, because the trial row was never touched and has fifteen days left. That’s the behavior the rep promised, and no code had to remember the promise.
What the check won’t tell you is what to do with the 14 dashboards Fenwick built while on Scale. That’s a product decision: I’d keep them readable and block new ones. The entitlement only says what the limit is.
Caching the check, and the outage
Cache the check, because it sits on every gated request. Key it by customer and feature, and drop the key whenever the writer touches that customer. Expiry is the case the writer never announces, so keep the lifetime short. A 60-second cache that serves a trial for 59 seconds too long is fine. An hour-long one is a bug report.
Decide the failure mode before the first outage. I’d serve the last known answer for a few minutes rather than lock paying customers out of something they bought.
Keep counting somewhere else. The grant holds the limit; the usage number comes from whatever meters it, whether that’s your own event pipeline or something like Stripe’s billing meters. Mixing the two in one table makes both harder to trust.
Stripe also shipped its own Entitlements API in 2024, which attaches features to products and lists the ones a customer’s active subscriptions include. It’s a reasonable input to the grant writer. I wouldn’t make it the table the product reads, because the trial a rep granted and the concession in an enterprise contract never passed through a checkout, and those are the rows that turn into if-statements when they have nowhere else to live.