Skip to main content
Plans bundle prices together into offerings for your customers. Each plan represents a specific pricing tier or custom deal — a rate card that belongs to one product, contains prices for that product’s metrics, defines billing frequency, and sets the currency. When customers subscribe, they choose a plan. That plan determines what they pay for each metric they consume.

​
Plan Structure

Every plan requires a product ID to associate it with a product, a name for internal identification (e.g., “Enterprise Q4 2024”), and an invoice display name that customers see on their invoices. You also set a billing interval (monthly or yearly), a currency that must match your account’s currency, and the prices — a list of price objects for the product’s metrics. Finally, the billing version controls which billing model the plan uses. It defaults to 1 (Standard Billing). Set it to 0 only for Legacy Billing integrations. See Billing Version below.

​
Billing Version

Plans have two billing models controlled by the billingVersion field:
  • Standard Billing (billingVersion: 1) — The default and recommended model. Required for features, metered entitlements, and Invoice 0 payment gating. Supports in_advance and in_arrears payment terms.
  • Legacy Billing (billingVersion: 0) — For existing integrations only. Also supports the instant payment term.
Omitting billingVersion defaults to Standard Billing. 
{
  "name": "Pro Plan",
  "billingVersion": 1
}
See Billing Versions for a full comparison of capabilities and constraints.

​
Billing Cadence

Plans use an ISO 8601 duration string for the billingCadence field:
ValuePeriod
P1MMonthly
P3MQuarterly
P1YYearly
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.
Parsing ISO 8601 durations in your codeThe billingCadence field uses ISO 8601 duration format (e.g., P1M for monthly, P3M for quarterly, P1Y for yearly).JavaScript / TypeScript — use Luxon:
import { Duration } from 'luxon';
const days = Duration.fromISO('P3M').as('days'); // ≈ 91.3
Python — use isodate:
import isodate

# Parse ISO 8601 duration from API response
duration = isodate.parse_duration('P3M')  # returns timedelta or Duration
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.

​
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 adds volume discounts, unlimited usage options, and 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 introduce graduated pricing, additional features, and no hard caps.

​
Examples

​
LLM Platform

A Developer Plan (monthly) charges 0.002/1Kinputtokensand0.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−monthforstorageand0.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 and offers pre-purchased compute blocks at a 40% discount, with a minimum commitment required.

​
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