member-console/docs/plan-management.md

audience

audience
operators

Plan Management

This document describes how operators configure plan ladders, manage automatic provisioning, perform manual transitions, and audit enrollment history.

Developers: see plan-architecture.md for where plan code lives and the sole-writer rule.

Overview

A plan ladder is a ordered set of plan products. Each organization is enrolled on at most one tier per ladder at a time. Transitions between tiers — upgrades, downgrades, initiations, and ends — are recorded in the transition history for audit.

When to use a plan vs. a regular product

Plans are an opt-in modeling choice for products that follow tier semantics: an organization should be on exactly one tier of a ladder, and moving between tiers means leaving the previous one. If that's not what you want, use a regular product instead.

Use a plan when:

• The product belongs to a graded set (e.g., Free → Standard → Pro) and an organization should hold exactly one at a time.
• You need an audit trail of transitions between tiers (who moved the org, when, why).
• Stripe subscription state (created/upgraded/downgraded/cancelled) should drive the org's tier directly.

Use a regular product (addon, usage, one-time) when:

• You want to grant the same thing multiple times (multiple gift cycles, stacked credits, parallel benefits).
• The product is independent of any tier — it adds to an org's entitlements rather than replacing them.
• You want simple grant/revoke semantics without ladder transitions or supersession.

If you find yourself wanting to grant the same plan twice to the same org, consider whether you need an extend (same tier, new grant) or whether the product should have been modeled as an addon. Plans enforce one-tier-per-ladder by design; addons and usage products do not. The Extend Current Tier action exists precisely for the legitimate case of issuing another grant on the same tier.

Developers: this distinction is enforced at the catalog layer (membership in plan_ladder_tiers is opt-in per product). See plan-architecture.md for the runtime consequence.

Making a plan available for purchase

Creating and publishing a plan product is not enough for a member to buy it. A product becomes purchasable only after it has passed every step on this path:

1. Draft → entitlement rules. Create the product and attach an entitlement set whose rules define the quantitative limits the tier grants (e.g. sites, storage_mb).
2. On a ladder. Put the product on a plan ladder as a tier. This is what makes it a plan — a product's plan-status is its ladder membership (Doc 31 Amendment #3 / Decision 121). A plan that is on no ladder is not a plan at all, and is invisible in the member catalog. To sell a single standalone plan, give it its own single-tier ladder — that is the idiom, not an off-ladder product.
3. Published, public, active. Set lifecycle_status = published, and mark the product Active and Public so it appears in the member catalog.
4. Priced. Add an active price on the product's Prices view.
5. Stripe-synced. The price must be mapped to a live Stripe price. Creating a price enqueues this sync automatically; until the mapping lands, the product shows sync pending and is not yet purchasable.

When all five hold, the member's plan card renders an enabled buy/upgrade control. Until then the card renders disabled ("Not available for purchase yet").

Reading the purchasability panel

The operator product edit page shows a Purchasability panel that evaluates each step above against the live state of the product and renders a single verdict — ✓ Purchasable or ⚠ Incomplete, naming exactly which preconditions are unmet, with inline guidance for each. The verdict is computed from the same gate the member catalog uses, so the panel never claims a product is purchasable while a member sees it disabled.

The panel also flags the invisible-limbo case: a published product that is neither on a ladder (so it is not a plan) nor assigned a product type. Such a product appears nowhere in the member catalog. Remediate it by putting it on a ladder (to sell it as a plan) or by setting a product type (add-on / usage / one-time) — typed products are purchasable off-ladder.

A NULL product_type is correct for two kinds of product: a plan (whose kind is derived structurally from its ladder membership) and a draft (not yet published). A published NULL-type product on no ladder is neither — it is the limbo the panel warns about.

Ladder Configuration

Creating a Ladder

1. Open the Operator panel and select the Plan Ladders tab.
2. Enter a unique slug (kebab-case identifier), a display name, and an optional description.
3. Click Create Ladder.

Attaching Tiers

1. From the ladder list, click Tiers on the ladder you want to configure.
2. Select a published plan product (products with product_type = NULL) and specify its rank.
3. Click Add Tier.

Tiers within a ladder are ordered by rank. Lower ranks are "lower" tiers; higher ranks are "higher" tiers. The typical pattern is:

• Rank 0 — Public / Free tier
• Rank 1 — Standard tier
• Rank 2 — Pro tier

Reordering Tiers

Tiers can be reordered by changing their rank values. The UI enforces unique ranks within a ladder.

Removing Tiers

A tier can be removed only when no active pool attachments exist for that tier. The UI shows the active attachment count per tier.

Deleting a Ladder

A ladder can be deleted only when it has no active attachments across all its tiers. Deleting a ladder also removes all tier memberships.

Auto-Provisioning Policy

Per-Organization-Type Default Plan

Each organization type can have a default plan configured by pointing at a billing.plan_ladders row. The default tier is always the rank-0 tier of that ladder, resolved at use-time. When a new organization of that type is created, the rank-0 product of the configured ladder is automatically granted to the organization's default pool.

The dropdown in the Operator panel sources from plan ladders only — every option renders as LadderName — rank-0 product name so the resolved default is visible inline. Products that are not the rank-0 tier of any ladder cannot be set as defaults; the Plan Ladders tab is the single source of truth for which products are eligible.

Applies to new organizations only. Changing the default plan for an org type does not affect existing organizations.

Backfilling Existing Organizations

To apply the current default plan to existing organizations:

1. Open the Operator panel and select the Org Types tab.
2. Find the org type with a configured default plan.
3. Click Backfill existing orgs.
4. Confirm the action.

The system iterates all organizations of that type, locks each pool row, and invokes ReapplyDefaultsForPool. The result reports:

• N updated — pools that received a new default grant
• M skipped — pools that were already at the target tier (idempotent)
• K failed — pools whose transition errored (per-org reasons listed below the summary)

Backfill is rejected if the org type has no default plan configured.

Manual Grant Workflows

Issue Grant

An operator can issue a grant to move a pool to a specific tier:

1. Open the Operator panel and select the Enrollment tab (or click Enrollment from the Organizations list).
2. Select the target organization.
3. In the Issue Grant card, choose a plan product, optionally set a valid until timestamp, and provide a reason.
4. Click Issue Grant.

The system:

• Creates a grant with grant_reason = 'manual' (or 'trial' if valid_until is set)
• Invokes Transition to attach the pool to the target tier
• Registers a Temporal workflow to expire the grant at valid_until only for trials

A grant with no valid_until is permanent. A grant with valid_until is a time-bounded trial; when it expires, the pool automatically transitions back to the organization's default tier (or detaches if no default is configured).

Grant Revocation

An operator can revoke an active grant:

1. On the enrollment page, locate the grant in the Active Grants table.
2. Click Revoke.
3. Confirm the action.

The system revokes the grant, ends the associated provision, and invokes Transition(End) to return the pool to its default tier.

Extend Current Tier

An operator can issue a new grant on the pool's current tier without changing position:

1. On the enrollment page, locate the Extend current tier card (visible only when the pool has an active plan attachment).
2. Provide a reason (e.g., "extending trial", "comp cycle").
3. Optionally set Expires at — when present, the new grant has a valid_until and a Temporal expiration workflow is scheduled. When empty, the extension is open-ended (comp/gift case).
4. Click Extend tier.

The system:

• Creates a new grant chained to the prior grant via extends_grant_id
• Invokes Transition with Extend=true to create a new provision + ladder attachment at the same tier
• Records a transition_type='extend' audit row with from_rank == to_rank
• Schedules GrantExpirationWorkflow keyed off the new grant's ID when Expires at is set, so trial extensions expire on their own clock and don't ride the original trial's expiry

Use this to extend a trial that is about to expire (set a new Expires at), comp an additional cycle during an outage, or gift a second period without disturbing the existing audit trail.

Downgrades and the tier-reduction policy

A downgrade returns a pool to a lower tier — triggered by a Stripe subscription cancellation (reconciled to Transition(End)), an operator Revoke, or a trial grant expiring. In every case the pool is returned to its organization-type default via ReapplyDefaultsForPool: if a default plan ladder is configured the pool is re-provisioned at that ladder's rank-0 product (a downgrade transition is recorded); if none is configured the pool legitimately goes off-ladder (an end transition is recorded).

What happens to resources already in use

When the new tier's limit is below the member's current usage (e.g. Standard's 16 sites → Public's 1, with 3 sites already created), the system applies the clamp policy:

• Existing resources are retained. Sites already created stay active and usable — nothing is deleted, suspended, or made read-only.
• New provisioning is blocked while usage is at or over the limit. The member cannot create new sites until they delete enough to fall back under the cap (AtomicIncrementUsage only succeeds while current_usage < resource_limit).
• The member UI shows the over-limit state (e.g. "3 of 1 sites used") and disables the create action with a clear reason.

clamp is the fixed tier-reduction policy today. The configurable tier_reduction_policy of Decision 125 (block / defer / clamp / force_reduce) is not yet implemented; a force_reduce flow that asks the member to pick which site to keep (others going read-only) and storage-based reduction are tracked as future work in status/issues.md.

Enrollment Audit

Reading Transition History

The enrollment page displays a chronological list of all pool_provision_transitions rows for each pool. Each row shows:

• Type — initiate, upgrade, downgrade, end, or extend
• From / To rank — the ladder position delta (extend shows equal ranks)
• Actor — system, webhook (Stripe), or the operator's display name
• Reason — free-form text or system-generated attribution
• Effective at — when the change took effect

Canonicalization vs. subscription_changes

pool_provision_transitions is the canonical source for plan-position history: what tier a pool held, when, and under whose authority. billing.subscription_changes records commercial mutations of the subscription (status changes, amount changes, etc.). A Stripe-driven upgrade is recorded in both tables because they answer different questions.

Corrections

Transition history is read-only. Errors or clarifications should be expressed by performing a new transition with an explanatory reason, not by editing historical rows.