Plan structure
Every plan requires a product ID to associate it with a product and a name for internal identification (e.g., “Enterprise Q4 2024”). You also set an invoice display name that customers see on their invoices. You also set a billing cadence (monthly, quarterly, or yearly), a currency that must match your account’s currency, and the prices — a list of price objects for the product’s metrics.Billing cadence
Plans use an ISO 8601 duration string for thebillingCadence field:
Monthly billing is the SaaS standard. It gives customers predictable costs and makes upgrades and downgrades straightforward.
Quarterly billing reduces payment processing overhead compared to monthly while keeping the commitment period shorter than annual.
Yearly billing collects revenue upfront and reduces payment processing overhead. Annual plans are often paired with a discount to incentivize commitment.
Choose based on your business model — or offer multiple cadences and let customers decide.
billingInterval deprecationThe older billingInterval string field ("monthly", "quarterly", "yearly") is deprecated. It is still returned in plan responses for backwards compatibility, but billingCadence is the source of truth. When creating or updating plans, prefer billingCadence. See the migration guide for the full mapping.Plan versions
When you change the prices of a plan, Paygentic does not edit them in place. It keeps the current prices as a plan version, creates a new version, and makes the new version the default that new subscriptions bill from. Each existing subscription has aversionPolicy that decides what the new version does to it. A floating subscription, the default, bills from the new version at its next billing period. A pinned subscription keeps the version it holds, so a customer who agreed to a rate keeps that rate. See Plan versions for how to read, create, and roll back a version.
Common strategies
Tiered offerings
Create multiple plans for market segmentation. A Hobbyist plan offers low per-unit costs with usage caps and community support. A Professional plan improves the rates and limits with email support. An Enterprise plan prices usage on a volume price so the per-unit rate falls at higher usage, removes the caps, and includes dedicated support. Each tier should offer clear value over the previous one.Customer-specific plans
For sales-led businesses, create custom plans per deal — “Acme Corp - Annual 2024”, “TechCo - Q1 Pilot”, “StartupX - Special Terms”. Each plan reflects negotiated pricing and can be tailored to the customer’s specific usage patterns.Freemium model
Combine free and paid tiers. A free plan sets zero cost for base metrics with hard usage limits, prompting upgrades when customers hit those limits. Paid plans add a volume price, more features, and no hard caps.Examples
LLM platform
A Developer Plan (monthly) charges $0.002/1K input tokens and $0.006/1K output tokens, rate-limited to 100 req/min. The Scale Plan (monthly) halves those token prices, raises the rate limit to 1,000 req/min, and adds fine-tuning at $5/hour. An Enterprise Plan (annual) offers custom token pricing, unlimited rate limits, priority GPU access, and SLA guarantees.Data warehouse
An On-Demand Plan (monthly) charges $0.023/GB-month for storage and $0.05/query-second for compute with no minimums. A Reserved Plan (annual) drops storage to $0.015/GB-month, sells compute in prepaid blocks through grant purchases, and applies a contracted minimum to each subscription through a quantity bound.Best practices
Clear naming. Use descriptive names that indicate target customer and terms. Logical progression. Each tier should offer clear value over the previous. Predictable costs. Help customers estimate their bills easily. Room to grow. Always have an upgrade path available.Next steps
- Plan versions — how a plan keeps a version for each set of prices
- Define prices — configure pricing models and payment terms
- Create subscriptions — connect customers to plans
- Meter Events — report usage for metered prices