Skip to content
OclavexOclavex Docs

Entitlements & offers

An entitlement is the central record: a customer’s grant to a product’s features, under a plan and a set of policies. Everything upstream (products, features, plans, add-ons) exists so you can issue good entitlements; everything downstream (activation, sessions, usage) flows from them.

Two independent states

Section titled “Two independent states”
  • Publication lifecycle — your editorial control; only a published entitlement can be activated. Draft and Published move freely in both directions. Revoking is deliberate: a published entitlement must be set back to Draft first — going straight from Published to Disabled is refused — and a revoked entitlement can be reinstated to Draft and re-published.
  • Subscription status — Pending, Trialing, Active, Paused, PastDue (reserved), Expired, Canceled. The runtime state the customer experiences, computed from the entitlement’s policies and dates — except Paused, which is stored, not computed: pause/resume is a separate, reversible hold that blocks activation and consumption while keeping the record editable.

Features are a snapshot

Section titled “Features are a snapshot”

When a product is added to an entitlement, its features are copied in — a snapshot of the product as it is at that moment. The entitlement keeps its own copy, so later edits to the product don’t change a live customer’s grant. What a customer effectively has at any moment is that snapshot, plus any active add-on grants, plus the values from the assigned plan, resolved together.

Product Seats 5 · Export ✓ as it is on grant day Product — edited later Seats 5 → 10 the next new grant copies 10 time Entitlement its own copy: Seats 5 · Export ✓ later product edits don't reach it Session copied again: Seats 5 · Export ✓ the running license grant · features copied in activate · copied again ✕ never flows into existing grants What the customer effectively has = this snapshot + the assigned plan's values + active add-on grants.

Its products come from a suite

Section titled “Its products come from a suite”

An entitlement licenses the products of one suite — the group of products you sell together. Assigning the suite is what puts products on the entitlement: every product in it is licensed, every product’s features go into the snapshot, and the plan you apply is one of that suite’s plans.

Most grants are for a single product, and that works the same way: pricing a product creates a suite holding just it, so a one-product entitlement is a suite of one. There is one mechanism to learn, not two.

Changing the suite replaces the products with the new suite’s products, and clears the plan — the new suite’s plans are not the old one’s, so the earlier choice cannot carry over.

Policies

Section titled “Policies”

Policies decide how the entitlement may be activated and for how long — they combine:

  • Seat allocation — fixed or floating seats, with a lease and offline grace.
  • Trial — a trial window, optionally starting on first activation.
  • Time-restricted — valid between two dates, or for a period after first use.
  • Subscription — recurring periods with renewal and expiry.
  • Anonymous try — on an offer only: the terms visitors are issued an entitlement under, with no account. See Try activation.

Offers

Section titled “Offers”

An offer is a saved template (products, features, policies) you author once and turn into entitlements repeatedly, instead of filling in every field per customer — it is what your orders start from. Offers are internal to your catalog: an end user never sees one, only what was ordered from it.

An offer has no customer. The organization, contact details, order number and references belong to the entitlement, and you supply them when you order one — so the same offer serves every customer, and saving an existing entitlement as an offer leaves that customer’s details behind.

Two settings let an offer issue by itself, without anyone in your team ordering from it. Automatic user issuance gives every user their own entitlement when they confirm their email address. Anonymous try gives every visiting device a short-lived one with no account at all, deleted once it expires or once that visitor signs up. Neither survives a copy of the offer: an offer you duplicate issues nothing until you say so.

External references

Section titled “External references”

On an entitlement, two reference fields keep it linked to your other systems: externalReference anchors the grant itself (scheme:type:id, e.g. stripe:subscription:sub_123), and customerExternalReference anchors the owning account (e.g. stripe:customer:cus_123). Neither is enforced unique — keep the anchors one-to-one yourself.

How it relates

Section titled “How it relates”