Pricing and Plan Modeling

Pathrule1 Rule • 2 Memories

Pricing and plan modeling separates what a customer buys, what it costs, and what the product enables so commercial changes do not become conditionals across the codebase. This bundle defines immutable price versions, stable entitlement keys, catalog migrations, and subscription snapshots. Unlike Subscriptions and Usage Billing, it owns the product catalog and commercial model rather than metering and recurring access processing.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

src/

billing/

catalog/

Never mutate a price already used by a subscription

Products, prices, and terms have separate identities

entitlements/

Entitlements are not plan names

Rules

Never mutate a price already used by a subscription/src/billing/cataloghighstrictCommercial changes create a new immutable price version with an explicit migration policy.

1	Commercial changes create a new immutable price version with an explicit migration policy. Editing amount, currency, interval, included quantity, or tax behavior in place silently changes the meaning of historical and active subscriptions. Enforce this boundary in /src/billing/catalog so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Give products and entitlements stable internal keys while treating display names as editable presentation.
4	- Create a new price identifier for any monetary or billing-term change and record its effective window.
5	- Keep legacy prices resolvable for invoices, credits, reporting, and subscriptions that have not migrated.
6	- Require a migration decision for existing customers: grandfather, opt in, scheduled move, or contract-specific handling.
7
8	Verification: Create an active subscription, publish a replacement price, and confirm the original invoice path and entitlement snapshot do not change until the chosen migration runs.

Memories

Entitlements are not plan names/src/entitlementsA plan is a commercial package, while an entitlement is a stable product capability with limits and conditions.

1	A plan is a commercial package, while an entitlement is a stable product capability with limits and conditions. Resolve a subscription or contract into entitlement keys at one boundary and let product code ask for capabilities such as projects.create or exports.monthly_limit.
2
3	Keep marketing labels, provider price IDs, and billing intervals out of authorization checks. Represent quantitative limits and feature access separately so an add-on can alter one without cloning a plan. Version entitlement mappings and preserve the resolved snapshot used for each access period. Keep the decision explicit at /src/entitlements; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /src/billing/catalog for commercial versions and the subscription billing pattern for access state. That related boundary consumes this decision and carries the evidence that proves it still holds.

Products, prices, and terms have separate identities/src/billing/catalogThe thing sold, the amount and cadence charged, and the contractual conditions change on different timelines and serve different consumers.

1	The thing sold, the amount and cadence charged, and the contractual conditions change on different timelines and serve different consumers. Model a product as the durable offer, a price as an immutable charge definition, and terms as eligibility, commitment, trial, renewal, or negotiated conditions.
2
3	Allow several prices to reference one product without implying identical entitlement mappings. Keep provider IDs as adapters around internal catalog IDs so a provider migration does not rewrite product logic. Snapshot the accepted commercial terms when an order or subscription begins. Keep the decision explicit at /src/billing/catalog; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /migrations for catalog transitions and /src/entitlements for capability resolution. That related boundary consumes this decision and carries the evidence that proves it still holds.

Why this pattern

Agents branch on labels such as pro or enterprise, mutate prices in place, and conflate billing intervals with product capabilities, making every pricing change risky.

Built for SaaS teams evolving plans, prices, packaging, trials, add-ons, and customer-specific terms.

Keeps your assistant from:

Plan-name conditionals spread through application code
Existing subscriptions changing when a catalog price is edited
Billing interval, price, and entitlement concepts collapsed into one field

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25