| name | model-plans-and-pricing |
| description | Model the plan / price / entitlement structure for a recurring-billing system — choose flat vs tiered vs per-seat vs usage/metered vs hybrid, define entitlements, and set proration/trial/coupon rules. Use when starting a billing build or re-pricing an existing product. |
Skill: Model Plans and Pricing
Turn a pricing intent into a concrete, buildable plan / price / entitlement model — the shape everything downstream (proration, metering, dunning, entitlements) depends on. Get this wrong and every customer must be re-priced to fix it.
When to use
- Standing up a new subscription-billing system.
- Re-pricing or re-packaging an existing product (adding usage, seats, tiers, add-ons).
- Deciding what a "plan" even is before touching a provider API.
Steps
- Establish how value is delivered and metered. Is value per-user (seats), per-consumption (API calls, GB, events), per-feature-tier, or flat access? The billing model should mirror the value axis — this is the single most important decision. Traverse
../../knowledge/billing-model-decision-tree.md.
- Pick the model — flat, tiered (feature tiers), per-seat, usage/metered, or hybrid (base + overage). Name explicitly what you are not adopting yet and why (e.g. "no per-seat until we have team accounts").
- Define the price objects. Currency(ies), billing interval(s) (monthly/annual + annual discount), plan/price ids, add-ons. Keep prices immutable and versioned — never mutate a live price; create a new one and migrate.
- Define entitlements separately from plans. List what each plan allows (limits, features, quotas). Entitlements are derived from billing state but are their own first-class model, so a plan change or dunning downgrade updates them predictably.
- Set the mid-cycle-change rules. Proration on upgrade/downgrade (immediate vs next-cycle, credit vs invoice), seat add/remove, trial-to-paid conversion, plan switch. This becomes the
proration-upgrade-test-matrix.
- Set trial and discount rules. Trial length, card-required-or-not, trial-end behavior; coupon/discount stacking rules and whether they apply to overage.
- Trace the correctness seams. Where does recognized revenue (ASC 606) come from, and where does sales-tax/VAT get calculated? A model that can't produce them is incomplete — flag the seam even if
finance / regulatory-compliance owns it.
Anti-patterns
- Baking per-seat into the schema when the product is really consumption (or vice versa) — the most expensive model mistake.
- Treating entitlements as an afterthought derived ad-hoc from the plan name in application code.
- Mutating a live price instead of versioning a new one.
- Selling usage-based before you can meter the usage accurately and idempotently.
- No explicit proration spec — "the provider handles it" until an upgrade produces a surprising invoice.
Output
A plan/price/entitlement model doc: value axis → chosen model (+ what's excluded) → price objects → entitlement map → proration/trial/coupon rules → revrec + tax seams. Feed it to billing-implementation-engineer and the billing-integration-runbook.
