Pricing Models

Understanding different pricing configurations and billing types in Autumn

Overview

Autumn supports any pricing model through its flexible price configuration system. Prices are attached to products and define how customers are charged.

The same product can have multiple prices (e.g., a base subscription fee + usage-based charges + one-time setup fee).

Price Types

There are two fundamental price types:

Fixed Prices

Flat fees that don’t depend on usage:

type FixedPriceConfig = {
  type: "fixed";
  amount: number;                // Price in cents (e.g., 2900 = $29.00)
  interval: BillingInterval;     // "month", "year", "one_off", etc.
  interval_count?: number;       // e.g., 3 for quarterly (every 3 months)
};

Example - Monthly subscription:

{
  type: "fixed",
  amount: 2900,                  // $29.00
  interval: "month"
}

Example - Annual subscription with discount:

{
  type: "fixed",
  amount: 29900,                 // $299.00 (save $49/year)
  interval: "year"
}

Example - One-time setup fee:

{
  type: "fixed",
  amount: 9900,                  // $99.00
  interval: "one_off"
}

Usage Prices

Variable pricing based on consumption:

type UsagePriceConfig = {
  type: "usage";
  
  // Feature being metered
  feature_id: string;
  internal_feature_id: string;
  
  // Pricing tiers
  usage_tiers: Array<{
    to: number | "infinite";     // Upper bound for this tier
    amount: number;              // Price per unit in cents
    flat_amount?: number;        // Optional flat fee for entering tier
  }>;
  
  // Billing configuration
  bill_when: "in_advance" | "start_of_period" | "end_of_period";
  interval: BillingInterval;
  interval_count?: number;
  
  // Optional
  billing_units?: number;        // Round up to nearest N units
  should_prorate?: boolean;      // Enable proration for continuous use
  
  // Stripe integration (managed by Autumn)
  stripe_meter_id?: string;
  stripe_price_id?: string;
  // ... other Stripe fields
};

Billing Intervals

Supported billing intervals:

enum BillingInterval {
  OneOff = "one_off",            // Single purchase
  Week = "week",
  Month = "month",
  Quarter = "quarter",            // 3 months
  SemiAnnual = "semi_annual",    // 6 months
  Year = "year"
}

Use interval_count for custom periods:

// Every 2 weeks
{ interval: "week", interval_count: 2 }

// Every 3 months (quarterly)
{ interval: "month", interval_count: 3 }

// Every 18 months
{ interval: "month", interval_count: 18 }

Billing Types

Autumn automatically classifies prices into billing types based on their configuration:

enum BillingType {
  OneOff = "one_off",                    // One-time charge
  FixedCycle = "fixed_cycle",            // Recurring flat fee
  
  UsageInAdvance = "usage_in_advance",   // Prepaid usage (credits)
  UsageInArrear = "usage_in_arrear",     // Postpaid usage
  InArrearProrated = "in_arrear_prorated" // Prorated continuous usage
}

Classification logic:

// One-off
type: "fixed" && interval: "one_off" → BillingType.OneOff

// Fixed recurring
type: "fixed" && interval: "month" → BillingType.FixedCycle

// Prepaid usage
type: "usage" && bill_when: "in_advance" → BillingType.UsageInAdvance

// Postpaid usage
type: "usage" && bill_when: "end_of_period" → BillingType.UsageInArrear

// Prorated continuous usage
type: "usage" && bill_when: "end_of_period" && should_prorate: true 
  → BillingType.InArrearProrated

Common Pricing Models

1. Simple Subscription

Flat monthly or annual fee:

// Pro Plan - $29/month
{
  prices: [
    {
      config: {
        type: "fixed",
        amount: 2900,
        interval: "month"
      }
    }
  ]
}

2. Tiered Subscription

Multiple plan tiers with different pricing:

// Starter: $9/mo
{ id: "starter", prices: [{ config: { type: "fixed", amount: 900, interval: "month" } }] }

// Pro: $29/mo  
{ id: "pro", prices: [{ config: { type: "fixed", amount: 2900, interval: "month" } }] }

// Enterprise: $99/mo
{ id: "enterprise", prices: [{ config: { type: "fixed", amount: 9900, interval: "month" } }] }

3. Usage-Based (Pay As You Go)

Charge based on consumption:

// API Calls - $0.001 per call, billed monthly
{
  prices: [
    {
      config: {
        type: "usage",
        feature_id: "api_calls",
        bill_when: "end_of_period",
        interval: "month",
        usage_tiers: [
          {
            to: "infinite",
            amount: 0.1           // $0.001 per call (in cents)
          }
        ]
      },
      entitlement_id: "ent_api_calls"
    }
  ],
  entitlements: [
    {
      id: "ent_api_calls",
      feature_id: "api_calls",
      allowance_type: "metered",
      allowance: null,            // Unlimited usage
      interval: "month"
    }
  ]
}

4. Prepaid Credits

Customers purchase credits upfront:

// 1,000 API Credits - $10 one-time
{
  prices: [
    {
      config: {
        type: "usage",
        feature_id: "api_calls",
        bill_when: "in_advance",
        interval: "one_off",
        usage_tiers: [
          {
            to: "infinite",
            amount: 0              // Prepaid, no per-use charge
          }
        ]
      },
      entitlement_id: "ent_api_calls"
    }
  ],
  entitlements: [
    {
      id: "ent_api_calls",
      feature_id: "api_calls",
      allowance_type: "metered",
      allowance: 1000,            // 1,000 calls included
      interval: "one_off"         // Never resets
    }
  ]
}

5. Subscription + Overages

Base subscription with included usage, charge for overages:

// Pro Plan: $29/mo + 10,000 API calls, $0.002 per call over limit
{
  prices: [
    // Base subscription
    {
      config: {
        type: "fixed",
        amount: 2900,
        interval: "month"
      }
    },
    // Overage pricing
    {
      config: {
        type: "usage",
        feature_id: "api_calls",
        bill_when: "end_of_period",
        interval: "month",
        usage_tiers: [
          {
            to: "infinite",
            amount: 0.2           // $0.002 per call over limit
          }
        ]
      },
      entitlement_id: "ent_api_calls"
    }
  ],
  entitlements: [
    {
      id: "ent_api_calls",
      feature_id: "api_calls",
      allowance_type: "metered",
      allowance: 10000,           // 10k calls included
      usage_limit: null,          // No hard limit, allow overages
      interval: "month"
    }
  ]
}

6. Tiered Usage Pricing

Different prices per tier of usage:

// Volume-based pricing:
// - First 10k calls: $0.01 each
// - Next 90k calls: $0.005 each  
// - Above 100k: $0.002 each
{
  config: {
    type: "usage",
    feature_id: "api_calls",
    bill_when: "end_of_period",
    interval: "month",
    usage_tiers: [
      {
        to: 10000,
        amount: 1               // $0.01
      },
      {
        to: 100000,
        amount: 0.5             // $0.005
      },
      {
        to: "infinite",
        amount: 0.2             // $0.002
      }
    ]
  }
}

Tiered pricing uses graduated tiers by default - each tier applies to the usage in that range. For example, usage of 15,000 calls would be charged as: (10,000 × $0.01) + (5,000 ×$0.005) = $125.

7. Seat-Based Pricing

Charge per active user/seat:

// Team Plan: $10/seat/month
{
  prices: [
    {
      config: {
        type: "usage",
        feature_id: "seats",
        bill_when: "end_of_period",
        interval: "month",
        should_prorate: true,    // Prorate when adding/removing seats
        usage_tiers: [
          {
            to: "infinite",
            amount: 1000          // $10 per seat
          }
        ]
      },
      entitlement_id: "ent_seats"
    }
  ],
  entitlements: [
    {
      id: "ent_seats",
      feature_id: "seats",
      allowance_type: "metered",
      allowance: null,            // Unlimited seats (will be tracked)
      interval: "month"
    }
  ]
}

Track seat usage:

// When user joins
await track({ featureId: "seats", value: 1 });

// When user leaves  
await track({ featureId: "seats", value: -1 });

8. Flat Tier Fees

Charge a flat fee when entering a tier:

// Data processing:
// - 0-1GB: Free
// - 1-10GB: $5 flat + $0.10/GB
// - 10GB+: $40 flat + $0.05/GB
{
  config: {
    type: "usage",
    feature_id: "data_processed_gb",
    bill_when: "end_of_period",
    interval: "month",
    usage_tiers: [
      {
        to: 1,
        amount: 0,
        flat_amount: 0
      },
      {
        to: 10,
        amount: 10,             // $0.10/GB
        flat_amount: 500        // $5 flat fee
      },
      {
        to: "infinite",
        amount: 5,              // $0.05/GB
        flat_amount: 4000       // $40 flat fee
      }
    ]
  }
}

9. Billing Units

Round usage up to nearest billing unit:

// Compute minutes - bill in 5-minute increments
{
  config: {
    type: "usage",
    feature_id: "compute_minutes",
    bill_when: "end_of_period",
    interval: "month",
    billing_units: 5,           // Round up to nearest 5 minutes
    usage_tiers: [
      {
        to: "infinite",
        amount: 10              // $0.10 per 5-min block
      }
    ]
  }
}

// Usage examples:
// - 3 minutes → billed as 5 minutes → $0.10
// - 7 minutes → billed as 10 minutes → $0.20
// - 12 minutes → billed as 15 minutes → $0.30

Proration

Control how price changes are handled mid-period:

type ProrationConfig = {
  on_increase: "prorate_immediately" | "prorate_next_period" | "no_prorate";
  on_decrease: "prorate_immediately" | "prorate_next_period" | "no_prorate";
};

Example:

{
  config: { /* ... */ },
  proration_config: {
    on_increase: "prorate_immediately",  // Charge difference immediately
    on_decrease: "prorate_next_period"   // Credit on next invoice
  }
}

Combining Prices

Products can have multiple prices that work together:

// Complete SaaS pricing example
{
  id: "professional",
  name: "Professional Plan",
  prices: [
    // 1. Base subscription
    {
      config: {
        type: "fixed",
        amount: 4900,
        interval: "month"
      }
    },
    // 2. Included API calls with overage
    {
      config: {
        type: "usage",
        feature_id: "api_calls",
        bill_when: "end_of_period",
        interval: "month",
        usage_tiers: [{ to: "infinite", amount: 0.15 }]
      },
      entitlement_id: "ent_api"
    },
    // 3. Per-seat pricing
    {
      config: {
        type: "usage",
        feature_id: "seats",
        bill_when: "end_of_period",
        interval: "month",
        should_prorate: true,
        usage_tiers: [{ to: "infinite", amount: 1500 }]
      },
      entitlement_id: "ent_seats"
    }
  ],
  entitlements: [
    {
      id: "ent_api",
      feature_id: "api_calls",
      allowance: 50000,          // 50k included
      interval: "month"
    },
    {
      id: "ent_seats",
      feature_id: "seats",
      allowance: null,
      interval: "month"
    }
  ]
}

Monthly invoice breakdown:

• Base fee: $49.00
• 3 additional seats × $15.00 =$45.00
• 12,500 overage calls × $0.0015 =$18.75
• Total: $112.75

Next Steps

• Learn about Features to understand what you’re pricing
• Explore Products and Plans to bundle prices together
• Read about Billing Lifecycle to understand when charges occur