Skip to main content

​
Plans

Plans are the products you sell to customers. They bundle pricing configurations with recurring fees into a complete offering.

​
What is a Plan?

A plan defines:
  • A recurring base fee (monthly, annually, etc.)
  • Which usage-based pricing to include
  • The billing frequency
{
  "name": "Pro Plan",
  "planCode": "pro",
  "currency": "USD",
  "billingFrequency": "MONTHLY",
  "basePrice": "50.00",
  "pricingIds": ["pricing_api_calls", "pricing_storage"]
}

​
Plan Structure

A plan consists of:
  1. Base Fee — Fixed recurring charge (can be $0)
  2. Usage Pricing — Variable charges based on metered usage
  3. Billing Terms — Frequency, currency, trial periods

​
Plan Fields

FieldRequiredDescription
nameYesDisplay name for the plan
planCodeYesUnique identifier (lowercase, no spaces)
currencyYesISO currency code
billingFrequencyYesMONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY
basePriceNoRecurring fee (defaults to 0)
pricingIdsNoArray of pricing configuration IDs to include
statusNoDRAFT, ACTIVE, ARCHIVED

​
Billing Frequencies

FrequencyPeriodUse Case
MONTHLY1 monthMost SaaS products
QUARTERLY3 monthsEnterprise contracts
SEMI_ANNUALLY6 monthsAnnual commitment discounts
ANNUALLY12 monthsLong-term contracts
Billing frequency affects when invoices are generated and usage is reset. Monthly plans generate 12 invoices per year; annual plans generate 1.

​
Plan Patterns

​
Freemium

No base fee, charges only for usage over free tier: 
{
  "name": "Free",
  "planCode": "free",
  "basePrice": "0.00",
  "pricingIds": ["pricing_with_1000_free_calls"]
}

​
Tiered Plans

Multiple plans with different base fees and usage rates: 
┌──────────────────────────────────────────────────────┐
│ Starter - $0/month                                    │
│   • 100 free API calls                               │
│   • $0.20 per additional call                        │
├──────────────────────────────────────────────────────┤
│ Pro - $50/month                                      │
│   • 5,000 free API calls                             │
│   • $0.08 per additional call                        │
├──────────────────────────────────────────────────────┤
│ Enterprise - $500/month                              │
│   • 100,000 free API calls                           │
│   • $0.02 per additional call                        │
└──────────────────────────────────────────────────────┘

​
Flat + Usage

Fixed fee covers a baseline, usage charges for overages: 
{
  "name": "Business",
  "planCode": "business",
  "basePrice": "99.00",
  "pricingIds": ["api_with_10k_included", "storage_per_gb"]
}

​
Plan Lifecycle

StatusDescription
DRAFTPlan is being configured, not available for contracts
ACTIVEPlan can be assigned to new contracts
ARCHIVEDPlan is deprecated, existing contracts continue but no new signups
Archiving a plan doesn’t affect existing customers. They continue on their current plan until they change or cancel.

​
Plans vs Contracts

Plans are templates. Contracts are instances assigned to customers.
  • Plan: “Pro costs 50/month+50/month + 0.08/API call”
  • Contract: “Acme Corp is on Pro, started Jan 1, renews monthly”
See Contracts for details.

​
Next Steps

How Usage-Based Billing Works

See how plans fit into the full billing flow

Create Your First Plan

Step-by-step guide

Plans API

API reference

Contracts

Assign plans to customers

Pricing

Configure usage pricing