Skip to content
OclavexOclavex Docs
Oclavex is in private preview, available to selected users. Public signup is blocked. Request access at [email protected].

Add-ons

An add-on is granted on top of an entitlement that already has a plan; an add-on is never the base grant. It packages two things together:

  • a suite — which suite’s catalog it may add features from;
  • feature choices — which catalog features are included, with any value overrides.

An add-on moves through Draft → Published → Archived; only a published add-on can be granted, and only a published add-on gives its features to the entitlements that hold it. Archived is final. An add-on can be deleted only while it’s a draft that has never been granted; archive any other.

Entitlement suite: Design Suite · plan: Pro Seats 5 Export ✓ the plan's features — the base Add-on published suite: Design Suite Seats +10 · on Pro Priority support included feature choices same suite base add-on grant starts · expires · revocable What the customer has right now Seats 15 5 + 10 Export ✓ from the plan, untouched Priority support ✓ added by the add-on Resolved when you ask — the entitlement's base is never edited.

Layer onto an existing plan

Section titled “Layer onto an existing plan”

Grant an add-on to an entitlement and its feature choices layer on top of whatever the entitlement’s own plan already grants — no re-picking the base plan per customer. When you resolve “what does this customer have right now”, active add-on grants overlay the entitlement’s base.

Keep selling an add-on while your plans move on

Section titled “Keep selling an add-on while your plans move on”

An add-on overlays the suite itself, not one version of its plans. A published plan set is never edited in place — an edit lands on a draft revision, and publishing that revision archives the previous one — and the add-on stays grantable across all of them: an entitlement on the older revision and one on the newer revision can both hold the same add-on grant.

An add-on can also aim a feature choice at named plans only — “these extra seats apply on Pro”. Plans are matched by name, so Pro in the new revision is the same Pro.

Sell an add-on through Stripe

Section titled “Sell an add-on through Stripe”

With the Stripe connector registered, an add-on can be sold as a subscription of its own, next to the customer’s plan:

  1. In Stripe, create a Product for the add-on with the metadata oclavex_addon set to the add-on’s code, and a recurring price under it with a lookup key. Add the lookup key to the connector’s allowed prices.
  2. Your app starts a checkout for that lookup key with the customer’s licence session, the same call that sells a plan. A customer who already pays for a plan can still buy the add-on; a customer who already has that add-on cannot buy it twice.
  3. When the subscription is paid, Oclavex grants the add-on to the customer’s entitlement. The grant is in force as long as the subscription is.

When the customer cancels, the add-on stays until the end of the period they paid for, then ends. If the subscription is ended at once in Stripe, the add-on ends at once. The customer’s plan is never changed by an add-on subscription, and cancelling the add-on never cancels the plan.

The add-on is a separate subscription, so the customer gets its own invoice and cancels it on its own in the billing portal. The add-on’s code must match a published add-on of the suite the customer’s plan belongs to, character for character.

How it relates

Section titled “How it relates”