Plans & products

Owostack models billing around plans (what customers subscribe to) and features (what they get). This page explains the relationships between these concepts and the design decisions behind them.

Plans

A plan represents a subscription tier — "Free", "Pro", "Enterprise". Each plan has:

• A price and billing interval (monthly, yearly, etc.)
• A currency tied to the payment provider
• A set of plan features that define what the customer gets
• An optional trial period
• A billing type: recurring (default) or one-time

Plans are lazy-synced to the payment provider. When the first customer checks out on a plan, Owostack creates the corresponding plan object on the provider if it doesn't already exist.

Plan groups and mutual exclusivity

Plans belong to a plan group. Within a group, plans are mutually exclusive — a customer can only have one active subscription per group.

This is a deliberate design choice. When a customer calls attach() with a new plan in the same group, Owostack interprets it as a plan switch (upgrade, downgrade, or lateral move) rather than a second subscription.

Plans in different groups are independent. A customer can subscribe to one plan from each group simultaneously. This is useful for modeling separate billing dimensions (e.g. a "compute" plan group and a "storage" plan group).

If no plan group is specified, each plan is treated as its own group.

Features and plan features

A feature is a product capability defined once (e.g. "API Calls", "Analytics Dashboard"). A plan feature is the specific configuration of that feature on a given plan.

The same feature can appear across multiple plans with different configurations:

This separation means you can change a feature's limit on the Pro plan without touching the Free or Enterprise plans.

Add-ons and credit packs

Add-ons are products that stack on top of a base subscription. They do not replace the existing plan.

The primary add-on type in Owostack is the credit pack — a purchasable bundle of credits tied to a specific credit system. When a customer buys a credit pack, their balance in that credit system increases.

Credit packs are not subscriptions. They are one-time purchases that top up a balance. The balance persists across billing periods and does not reset.

Billing types

Owostack supports two billing types:

• Recurring — standard subscription billing with automatic renewals
• One-time — a single payment that grants access permanently (or until revoked)

For one-time plans, Owostack creates an active subscription with no billing period end. Features remain available indefinitely.

Provider synchronization

Plans live in two places: the Owostack database and the payment provider. Owostack uses lazy synchronization — it creates the provider-side plan the first time a customer needs to check out, not when you create the plan in the dashboard.

This means you can define plans freely without worrying about provider-side rate limits or conflicts. The provider plan is created once and reused for all subsequent checkouts.

Code-managed vs dashboard-managed

Plans can be created through the dashboard or defined in code using the catalog. Both coexist safely. See Catalog & Sync Model for details on how conflicts are resolved.

Updating plans

Changing a plan’s features affects entitlements immediately for customers on that plan.

See:

• Plans (Dashboard)
• Plan switching