Skip to Content
Living documentation — last reviewed 2026-05-28
DecisionsADR-0019: Deferred plan transitions and member-controlled cycle advance

ADR-0019: Deferred plan transitions and member-controlled cycle advance

Status: Accepted Date: 2026-09-11 Context owner: Saar Issue: TKN-310 

Context

ADR-0016 made upgrades immediate and prorated. TKN-310’s resolved model replaces that policy: a billing cycle must remain understandable, with one ordinary boundary transition rather than mid-cycle price and entitlement arithmetic.

The authoritative product record is the Linear issue’s resolved model comment  and D1–D6 decisions , not the superseded proration proposal in the issue description.

Decision

  1. Default every plan transition to the next billing boundary. The current plan, access, credits, and billing date remain unchanged before then.
  2. Persist the agreed target price and currency when scheduling. The boundary charge uses those terms, not a later catalog price.
  3. Charge a scheduled upgrade before applying its target plan. Downgrades and laterals apply at the boundary before their charge.
  4. A member or authorized staff member may explicitly advance a one-window billing cycle. It charges now and opens a new period now. If a transition is scheduled, advance applies its target plan, target entitlement, and booking sweep; the unexpired old period is forfeited without credit.
  5. Advance is unavailable for an open unpaid term, a cancellation notice, or a multi-window cycle. Cardless non-gift changes are refused.
  6. At most one plan change may be pending. Cancelling it frees the slot; cancel-then-reschedule is permitted.
  7. The existing immediate-change machinery remains available only under the specified interval and PostHog policy; it is not a default member path.

Consequences

  • Members have one predictable default transition point and no prorated-credit rounding rules.
  • Price commitments survive catalog edits, which requires a complete schedule-field lifecycle and durable payment/fulfillment reconciliation.
  • Advance-cycle is a money-moving action and must use the same eligibility, quote, idempotency, entitlement, and notification path for staff and members.
  • Long billing cycles need quota windows. Member-facing advance is intentionally unavailable once a cycle has more than one quota window.

Alternatives considered

  • Immediate prorated upgrades. Rejected: it changes the cycle anchor and requires price/credit rounding and repeated-upgrade policy.
  • Live boundary prices. Rejected: a member must be charged the price they accepted when scheduling.
  • Swap before charging upgrades. Rejected: a declined charge must not grant higher-plan access through the retry window.
ADR-0018: Org-scoped audit logging (FIT-20)ADR-0020: Scheduled jobs run from a BullMQ queue