Docs / 09 of 14
Managing entitlements
How Entitlement rows decide product access: source, status, accessLevel, grace, purchases, packs, and what happens on downgrade, refund, or trial end.
An Entitlement is the record that answers “can this Organization use this Product.” It is materialized on the Organization, not computed ad hoc in the browser. Feature screens read it. They do not invent access.
List everything the org can use at /dashboard/products, or via GET /api/entitlements (org:member or API key scope entitlements:read).
What an Entitlement contains
Each row is one (Organization, Product, source):
| Field | Values that matter to an admin |
|---|---|
source | subscription · purchase · trial · grant |
status | active · trialing · grace · revoked · expired |
accessLevel | full · read_only · none |
endsAt | Period or trial end. purchase rows are perpetual (endsAt null) unless refunded. |
graceEndsAt | When grace ends. |
unitCap | Metered allowance for the period, when the product has one. |
versionMajorCap | On purchase: free updates within this major version. |
Precedence when several rows exist for the same product: grant > purchase > subscription > trial. If any live row is full, full wins. A paid purchase is not reduced to read_only by a lapsed subscription row.
grant is a staff override (design partners, demo). Workspace admins cannot create grant rows.
How you get access
Plan inclusion. Live subscription statuses trialing, active, and past_due include published products whose tierIncludedFrom rank is less than or equal to the plan rank (starter 1, growth 2, scale 3, enterprise 4), plus explicit plan includes, minus explicit excludes. Add-on catalog flags do not grant access by themselves; they only mark a price. If the product is included, the card reads “Included in your plan.” There is no buy button.
Trial. New Organization, 14 days of growth. source is trial, status trialing, accessLevel full, endsAt = trialEndsAt. Unit caps are tightened for trial. self-hosted artifacts stay locked.
One-time purchase. source purchase, status active, accessLevel full, perpetual. Survives plan change, cancellation, and a fully unsubscribed org. Runs still spend credits.
Pack. The pack Product is entitled, and member products receive expanded rows with reason pack:<pack-slug>.
This build. Stripe checkout is stubbed. POST /api/checkout/session creates a preview order and does not create Entitlements. Live payment is Not yet available. Completable access today is the Growth trial (and any grant a staff member has issued). Joining the waitlist at checkout stores the cart slugs. No charge.
Read the decision
GET /api/entitlements/[productSlug] returns a Decision:
allowed: false,reason: not_entitled— no row. Upsell copy: included from a highertier, or buyone-time.allowed: false,reason: expired— rows exist but none are live.allowed: true,level: full— Run and Schedule are on.allowed: true,level: read_only— UI and exports open; runs and triggers off.
Adding a catalog item you already have live returns 409 already_entitled with the Entitlement source.
Status transitions you will see
| Event | What happens |
|---|---|
| Trial ends, no card | applyLoss → grace, read_only, 14 days, then revoked / none. |
Payment fails (past_due) | Subscription-sourced rows → grace / read_only. Dunning window: current period end + 7 days. On invoice.paid, they return to active / full. |
| Cancel at period end | No change until the period ends, then 14-day grace. |
Downgrade (for example scale → growth) | Products still included keep active. Products only on the higher tier go to 14-day grace / read_only. Purchased licenses stay full. |
Refund of a purchase | Immediate revoked / none. No grace on a refund. |
| Hard spend ceiling | Runs stop. Entitlement rows are unchanged. See Credits and usage. |
Purchased licenses and purchase credits survive churn. Tier inclusions do not.
What read_only means in the product
The product UI opens. Past runs, outputs, and exports are available. Run, Schedule, and agent triggers are disabled. API calls for that product return 403 entitlement_read_only. Scheduled agents are paused, not deleted.
Version ceilings
A purchase may set versionMajorCap. Updates within that major are included. The next major is a paid upgrade. There is no silent behavior change on a live workflow: you get a changelog, not a migration project. Installing a next-major artifact without entitlement is Not yet available as a self-serve flow; contact support if a product page announces a major you cannot open.