What an entitlement is
An entitlement is akey, a type, a mode and a value, attached to a subscription version:
A
credit_allocation entitlement carries an allocation (amount, credit_type of monetary or units, rollover_enabled and an optional rollover_max_periods) and a timing (recurrence of recurring or one_off, with an interval of monthly, quarterly, semi_annual or yearly).
Alguna does not meter your application’s usage against an entitlement. Your application asks what the customer is entitled to and enforces it. To bill or limit by consumption, send usage events and use a credit-allocation entitlement when the customer should draw down an included balance.
Defining entitlements
Entitlements travel with the offer, so they are set where the offer is defined:- On a plan — the
entitlementsarray on Create a plan, or when building the plan in the dashboard. Every subscription created from the plan inherits them. - On a subscription version — the
entitlementsarray on Create a new subscription version or Replace a draft subscription version (the full set for that version), or the subscription editor in the dashboard. Use this to grant one customer something their plan does not.
entitlement_key, type, mode and (for scalar types) value:
Reusable entitlement configs, templates, and the transition policies that decide what happens to active grants when a version changes are managed in the dashboard under Entitlements. The public API sets entitlement values on plans and versions and reads them back; it does not manage configs or policies.
Reading entitlements
Three endpoints answer “what can this customer do?”.One entitlement on a subscription
Get a specific entitlement —GET /subscriptions/{id}/entitlements/{key}
All entitlements on a subscription
List active entitlements —GET /subscriptions/{id}/entitlements returns every entitlement on the subscription’s current published version, static and grant-based.
All entitlements for a customer
List active entitlements for a customer —GET /customers/{id}/entitlements flattens the entitlements across all of the customer’s active subscriptions. Each entry carries the subscription_id it came from. The {id} accepts the Alguna customer ID, one of the customer’s aliases, or a connected-account external ID such as a Stripe customer ID, so you can call it with the identifier you already hold.
value is always returned as a string, whatever the entitlement’s type. Parse it according to type. An entry with a null subscription_id and version_id comes from your organization’s default entitlement profile rather than from a subscription.Checking access in your application
subscription.version.updated webhook fires when that happens, so you can invalidate on the event.
Credit allocations
For acredit_allocation entitlement, the entitlement tells you what was allocated; the balance and the draw-down live in the credits API. Check the remaining balance before allowing consumption with GET /subscriptions/{id}/credits/balance:
Version changes
When a subscription moves to a new version or phase that changes or removes a credit, a credit transition decides what happens to the credits the customer already has:
When rolled-over credits are moved but the new phase has no matching credit, a third choice, If the new phase has no matching credit, says whether to keep them or remove them. Credits match across phases by their template key; see Credit templates.
Where the choice comes from
Each change takes the first of these that is set:- A choice made on the subscription. When you save phases that change or remove credits, the subscription builder shows what will happen to existing credits and the Existing credits dialog lets you choose per credit. Use defaults keeps the defaults below; Apply decisions saves your choices with the phases.
- The customer’s setting. In the Credits section of Customers → [Customer] → Profile, When a subscription changes credits shows the organization default. Override sets a different rule for that customer, and Reset returns to the organization default.
- The organization default, under Settings → Workflows → Billing → Credit transitions, labelled When a phase changes credits.
- The standard default, when none of the above is set: active credits are kept until they expire and rolled-over credits are kept.
2026-04-01 API applies these defaults to version changes; it does not set a transition per change. See Versioning and Amendments.
Credit templates
The Entitlements page has a Credit templates tab for credits you reuse: how much, how often it is granted and whether unused credit rolls over. Add a template to any plan or subscription instead of configuring the credit by hand each time. Each template can carry a Template key, which matches its credits across subscription phases when a plan changes, so rolled-over credits can move into the matching credit of the new phase. With no templates yet, the tab offers starting points such as Monthly allowance, Onboarding credit and Quarterly units with rollover.Best practices
Use stable keys
Your application reads entitlements by key. Keep keys identical across plans so an upgrade never needs a code change.
Meter separately
Entitlements describe access. Bill consumption with metrics and credits.
Cache reads
Entitlements only change when a version is published; invalidate on
subscription.version.updated.Fail closed
Treat a missing entitlement (404) as no access, not unlimited access.
Next steps
Plans
Define entitlements once on the offer.
Subscription Versioning
Entitlements are read from the current published version.
Credits & Wallets
Meter and draw down credit allocations.
Webhooks
Invalidate caches when versions change.