Skip to main content
The autumn.config.ts file defines your pricing plans, features, and billing logic. This reference covers every parameter and option available.
Configuration files use TypeScript with full import support. Export your features and plans, then sync them with atmn push.

​
Configuration Structure

Your config file exports features and plans:
autumn.config.ts
import { feature, plan, planFeature } from 'atmn';

// Define features first
export const messages = feature({
  id: 'messages',
  name: 'AI Messages',
  type: 'metered',
  consumable: true
});

// Use features in plans
export const pro = plan({
  id: 'pro',
  name: 'Professional',
  items: [
    planFeature({
      feature_id: messages.id,
      included: 1000
    })
  ]
});

​
Features

Features define what can be metered, gated, or billed in your application.

​
feature(config)

​
id
string
required
Unique identifier for the feature. Used in API calls and SDK methods.
​
name
string
required
Display name for the feature shown in dashboard and billing UI.
​
type
enum
required
Feature type determining behavior:
  • "boolean" - Simple feature flag (on/off)
  • "metered" - Usage-based feature with consumption tracking
  • "credit_system" - Credit-based feature with cost mapping
​
consumable
boolean
Required for metered features. Determines usage behavior:
  • true - Single-use (consumed when used) like API calls, messages
  • false - Continuous-use (ongoing usage) like seats, storage
Not applicable for boolean or credit_system types.
​
credit_schema
array
Required for credit_system features. Maps metered features to credit costs.Array of objects with:
  • metered_feature_id: string - ID of the metered feature
  • credit_cost: number - Credits required per usage
​
event_names
string[]
Optional array of event names that trigger this feature. Used for webhook integration.
​
archived
boolean
Whether the feature is archived. Archived features are hidden but preserved for existing data.

​
Feature Types

​
Boolean Feature

Simple on/off feature flags: 
export const sso = feature({
  id: 'sso',
  name: 'SSO Authentication',
  type: 'boolean'
  // No consumable field allowed
});

​
Metered Feature (Single-Use)

Features consumed when used - like API calls or messages: 
export const apiCalls = feature({
  id: 'api_calls',
  name: 'API Calls',
  type: 'metered',
  consumable: true  // Consumed when used
});

​
Metered Feature (Continuous-Use)

Features for ongoing usage - like seats or storage: 
export const seats = feature({
  id: 'seats',
  name: 'Team Seats', 
  type: 'metered',
  consumable: false  // Ongoing usage
});

​
Credit System Feature

Credit-based features with cost mapping: 
// First define the underlying metered features
export const basicModel = feature({
  id: 'basic_model',
  name: 'Basic AI Model',
  type: 'metered',
  consumable: true
});

export const premiumModel = feature({
  id: 'premium_model', 
  name: 'Premium AI Model',
  type: 'metered',
  consumable: true
});

// Then define the credit system
export const aiCredits = feature({
  id: 'ai_credits',
  name: 'AI Credits',
  type: 'credit_system',
  credit_schema: [
    { metered_feature_id: basicModel.id, credit_cost: 1 },
    { metered_feature_id: premiumModel.id, credit_cost: 5 }
  ]
});

​
Plans

Plans combine features with pricing to create your subscription tiers.

​
plan(config)

​
id
string
required
Unique identifier for the plan. Used in checkout and subscription APIs.
​
name
string
required
Display name for the plan shown in pricing tables and billing.
​
description
string
Optional description of the plan for marketing copy.
​
group
string
Optional grouping category for organizing plans in the dashboard.
​
add_on
boolean
default:"false"
Whether this plan is an add-on that can be purchased alongside other plans.
​
auto_enable
boolean
default:"false"
Whether to automatically assign this plan to new customers.
​
price
object
Base subscription price for the plan:
  • amount: number - Price in cents (e.g., 2000 = $20.00)
  • interval: string - Billing interval: "month", "quarter", "semi_annual", "year"
​
items
array
required
Array of planFeature() objects defining what’s included in the plan.
​
free_trial
object
Optional free trial configuration:
  • duration_length: number - Trial duration (e.g., 14)
  • duration_type: string - Duration type: "day", "month", "year"
  • card_required: boolean - Whether card is required to start trial

​
Basic Plan Structure

export const pro = plan({
  id: 'pro',
  name: 'Professional',
  description: 'Perfect for growing teams',
  group: 'main',
  price: {
    amount: 5000,    // $50.00
    interval: 'month'
  },
  free_trial: {
    duration_length: 14,
    duration_type: 'day',
    card_required: true
  },
  items: [
    // Plan features go here
  ]
});

​
Plan Features

Plan features define what’s included with each plan and how it’s priced.

​
planFeature(config)

​
feature_id
string
required
ID of the feature to include in this plan.
​
included
number
Amount included for free with the plan. For boolean features, omit this field.
​
reset
object
Reset configuration for included amounts:
  • interval: string - Reset interval: "hour", "day", "week", "month", "quarter", "semi_annual", "year"
​
price
object
Pricing configuration for usage beyond included amounts.
​
proration
object
Proration rules for quantity changes:
  • on_increase: string - "prorate" or "charge_immediately"
  • on_decrease: string - "refund_immediately", "prorate", or "no_action"
​
rollover
object
Rollover configuration for unused included amounts:
  • max: number - Maximum amount that can roll over
  • expiry_duration_type: string - "month", "year", or "forever"
  • expiry_duration_length: number - Expiry duration (ignored if type is “forever”)

​
Pricing Configuration

The price object supports multiple billing models:
​
amount
number
Price per billing unit in cents.
​
interval
string
Billing interval: "month", "quarter", "semi_annual", "year". Omit for one-time charges.
​
billing_method
enum
Billing method:
  • "usage_based" - Charge based on actual usage
  • "prepaid" - Customer purchases fixed quantities upfront
​
billing_units
number
default:"1"
Number of units per price. E.g., $5 per 100 credits = amount: 500, billing_units: 100
​
tiers
array
Tiered pricing configuration (alternative to flat pricing):
  • to: number | "inf" - Usage threshold for this tier
  • amount: number - Price per unit in this tier
​
max_purchase
number
Maximum quantity that can be purchased (for usage_based billing).

​
Plan Feature Examples

​
Free Allocation with Reset

planFeature({
  feature_id: messages.id,
  included: 1000,
  reset: { interval: 'month' }
  // No price = free allocation
})

​
Usage-Based Pricing

planFeature({
  feature_id: seats.id,
  included: 5,           // 5 free seats
  price: {
    amount: 1000,        // $10.00 per additional seat
    interval: 'month',
    billing_method: 'usage_based',
    billing_units: 1
  }
})

​
Prepaid Packages

planFeature({
  feature_id: credits.id,
  price: {
    amount: 500,         // $5.00 per package
    billing_units: 100,  // 100 credits per package
    billing_method: 'prepaid'
  }
})

​
Tiered Pricing

planFeature({
  feature_id: apiCalls.id,
  price: {
    tiers: [
      { to: 1000, amount: 1 },     // First 1000: $0.01 each
      { to: 10000, amount: 0.8 },  // Next 9000: $0.008 each  
      { to: 'inf', amount: 0.5 }   // Beyond 10k: $0.005 each
    ],
    billing_method: 'usage_based',
    interval: 'month'
  }
})

​
Advanced Configuration

planFeature({
  feature_id: storage.id,
  included: 10,          // 10 GB included
  price: {
    amount: 200,         // $2.00 per additional GB
    interval: 'month',
    billing_method: 'usage_based',
    max_purchase: 100    // Max 100 GB additional
  },
  proration: {
    on_increase: 'prorate',
    on_decrease: 'refund_immediately'
  },
  rollover: {
    max: 50,             // Max 50 GB rollover
    expiry_duration_type: 'month',
    expiry_duration_length: 3  // Expires after 3 months
  }
})

​
Boolean Features

planFeature({
  feature_id: sso.id
  // No included amount or price - just grants access
})

​
Complete Example

Here’s a comprehensive example showcasing different feature types and pricing models: 
import { feature, plan, planFeature } from 'atmn';

// === Features ===

// Single-use metered feature
export const messages = feature({
  id: 'messages',
  name: 'AI Messages',
  type: 'metered',
  consumable: true
});

// Continuous-use metered feature  
export const seats = feature({
  id: 'seats',
  name: 'Team Seats',
  type: 'metered', 
  consumable: false
});

// Boolean feature flag
export const sso = feature({
  id: 'sso',
  name: 'SSO Authentication',
  type: 'boolean'
});

// Credit system with underlying features
export const basicCalls = feature({
  id: 'basic_api_calls',
  name: 'Basic API Calls',
  type: 'metered',
  consumable: true
});

export const premiumCalls = feature({
  id: 'premium_api_calls', 
  name: 'Premium API Calls',
  type: 'metered',
  consumable: true
});

export const apiCredits = feature({
  id: 'api_credits',
  name: 'API Credits',
  type: 'credit_system',
  credit_schema: [
    { metered_feature_id: basicCalls.id, credit_cost: 1 },
    { metered_feature_id: premiumCalls.id, credit_cost: 5 }
  ]
});

// === Plans ===

export const free = plan({
  id: 'free',
  name: 'Free',
  description: 'Perfect for getting started',
  auto_enable: true,  // Auto-assign to new customers
  items: [
    planFeature({
      feature_id: messages.id,
      included: 100,
      reset: { interval: 'month' }
    }),
    planFeature({
      feature_id: seats.id,
      included: 2
    })
  ]
});

export const pro = plan({
  id: 'pro', 
  name: 'Professional',
  description: 'For growing teams',
  price: {
    amount: 2000,      // $20.00
    interval: 'month'
  },
  free_trial: {
    duration_length: 14,
    duration_type: 'day',
    card_required: true
  },
  items: [
    // Free allocation with reset
    planFeature({
      feature_id: messages.id,
      included: 2000,
      reset: { interval: 'month' }
    }),
    
    // Usage-based pricing with included amount
    planFeature({
      feature_id: seats.id,
      included: 5,
      price: {
        amount: 800,     // $8.00 per additional seat
        interval: 'month',
        billing_method: 'usage_based',
        billing_units: 1
      }
    }),
    
    // Boolean feature (just access)
    planFeature({
      feature_id: sso.id
    })
  ]
});

export const enterprise = plan({
  id: 'enterprise',
  name: 'Enterprise', 
  description: 'For large organizations',
  price: {
    amount: 10000,     // $100.00
    interval: 'month'
  },
  items: [
    // Tiered pricing
    planFeature({
      feature_id: messages.id,
      price: {
        tiers: [
          { to: 5000, amount: 0.02 },   // First 5k: $0.02 each
          { to: 20000, amount: 0.015 }, // Next 15k: $0.015 each
          { to: 'inf', amount: 0.01 }   // Beyond 20k: $0.01 each
        ],
        billing_method: 'usage_based',
        interval: 'month'
      }
    }),
    
    // Unlimited seats
    planFeature({
      feature_id: seats.id
      // No included limit or price = unlimited
    }),
    
    planFeature({
      feature_id: sso.id
    })
  ]
});

// Add-on for extra credits
export const creditTopUp = plan({
  id: 'credit_top_up',
  name: 'Credit Top-up',
  description: 'Extra API credits',
  add_on: true,  // Can be purchased with other plans
  items: [
    planFeature({
      feature_id: apiCredits.id,
      price: {
        amount: 1000,        // $10.00 per package
        billing_units: 1000, // 1000 credits per package
        billing_method: 'prepaid'
      }
    })
  ]
});
This configuration creates a complete pricing structure with multiple plan tiers, different billing models, and various feature types that can handle most SaaS pricing scenarios.