How entitlements resolve and enforce
Plan defaults, per-subscription overrides, and how a grant is checked.
A customer's entitlements come from two places: the defaults on their plan, and any overrides on their subscription. yRecurring combines them the moment they are checked, so what a customer can do is always up to date.
Defaults on the plan, overrides on the subscription
You attach features to a plan as its defaults. Every subscription on that plan starts with those. Then, for a single customer, you can override a feature on their subscription: give them more seats, turn a feature on early, or take one away.
| Feature | Plan default | Subscription override | Effective |
|---|---|---|---|
| seats limit | 10 | 25 | 25 |
| ai.copilot switch | off | not set | off |
| workflows.active limit | 5 | removed | none |
A subscription override wins over the plan default. With no override, the default applies. An override can also remove a feature entirely.
The effective entitlement is worked out by laying the subscription's overrides on top of the plan's defaults:
- With no override, the plan default applies.
- An override replaces the default for that one subscription.
- An override can also remove a feature, so the customer does not have it even though the plan does.
This is resolved fresh every time it is checked. It is never frozen, so a change to a plan default or a subscription override takes effect right away.
How a grant is enforced
When your customer tries to do something gated, yRecurring checks their effective entitlement:
- For a switch, is it on?
- For a limit, are they within the cap?
- For a quota, do they have allowance left this period?
If the check fails, the action is refused with a signal your app can turn into an upgrade prompt, so the customer sees "you have reached your plan's limit, upgrade to continue" rather than a blank error. Reading data is never blocked; only the gated action is.
In the API
Set a plan's default entitlements through the /v1/products/{id}/entitlements endpoints, and override them per subscription through /v1/subscriptions/{id}/entitlements. Reading a subscription's effective entitlements is a plain read. See the API reference. The features themselves are defined in the catalog covered on the features page.
Edge cases
- Overrides are per subscription. Overriding one customer's entitlement does not touch anyone else on the same plan.
- Resolution is never stored. It is worked out at check time, so changes apply immediately.
- Reads are never gated. Only the action a feature guards is checked; looking at data always works.