Plans and versions
A plan is a stable name, such as pro, with a key matching ^[a-z][a-z0-9_]{0,63}$. What a plan grants lives in its versions.
Drafts and publishing
Section titled “Drafts and publishing”- A plan has at most one draft. Saving the draft replaces it entirely (
PUT /v1/plans/{plan_key}/draft). - Publishing turns the draft into the next version number: 1, 2, 3… A draft has no number until it’s published.
- A version can leave features out. Those fall through to the feature’s default, or aren’t granted.
Published versions never change
Section titled “Published versions never change”Once published, a version’s values are fixed. Every subscription is pinned to one version, so publishing version 2 changes nothing for Customers on version 1.
To move Customers to a new version, change each subscription’s version explicitly (POST /v1/subscriptions/{subscription_id}/change-plan-version). The change is recorded in the audit log. Nobody’s entitlements change because someone edited a plan.
Typical uses
Section titled “Typical uses”- A new price or limit for new Customers only: publish a new version and assign it to new subscriptions. Existing Customers keep theirs.
- A change for everyone: publish, then move each subscription to the new version.
- A free tier: a
freeplan, and a real subscription to it for every Customer who hasn’t paid.