Useautumn Autumn Autumn

Autumn Pricing Model Design

This guide helps you design your pricing model for Autumn. Autumn uses a configuration file (autumn.config.ts) to define your features and plans.

Before starting: Check for an autumn.config.ts in the project root. If it doesn't exist, run npx atmn init to log in and generate the file. If you already have a config you want to modify, run atmn pull to sync it from Autumn first.

Step 1: Understand Your Pricing Needs

Before building, consider:

1. What features do you want to offer? (API calls, seats, storage, etc.)
2. What plans do you want? (Free, Pro, etc.)
3. How should usage be measured and limited?

Features

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

feature(config)

Feature Types

Boolean -- simple on/off flag:

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

Metered, consumable -- used up and replenished (messages, API calls):

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

Metered, non-consumable -- ongoing usage (seats, storage):

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

Credit system -- maps multiple metered features to credit costs:

export const basicModel = feature({
  id: 'basic_model',
  name: 'Basic Model',
  type: 'metered',
  consumable: true,
});

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

export const credits = feature({
  id: 'credits',
  name: 'AI Credits',
  type: 'credit_system',
  creditSchema: [
    { meteredFeatureId: basicModel.id, creditCost: 1 },
    { meteredFeatureId: premiumModel.id, creditCost: 5 },
  ],
});

If you set the price per credit to 1 cent, credits become monetary credits (eg, 5 credits = $0.05 per premium message).

Plans

Plans combine features with pricing to create your subscription tiers, add-ons, and top-ups.

plan(config)

Price intervals: "month" | "quarter" | "semi_annual" | "year" | "one_off"

Trial duration types: "day" | "month" | "year"

Plan Items

Plan items define what each plan includes -- usage limits, pricing, and billing behavior.

item(config)

Reset intervals: "hour" | "day" | "week" | "month" | "quarter" | "semi_annual" | "year"

Proration options:

• onIncrease: "prorate" | "charge_immediately"
• onDecrease: "prorate" | "refund_immediately" | "no_action"

Pricing Patterns

The price object on a plan item supports different billing models.

Usage-based -- charge based on actual usage

item({
  featureId: seats.id,
  included: 5,
  price: {
    amount: 10,
    interval: 'month',
    billingMethod: 'usage_based',
    billingUnits: 1,
  },
})

Prepaid -- customer buys a fixed quantity upfront

item({
  featureId: credits.id,
  price: {
    amount: 5,
    billingUnits: 100,
    billingMethod: 'prepaid',
  },
})

Tiered -- price changes based on usage volume

item({
  featureId: apiCalls.id,
  price: {
    tiers: [
      { to: 1000, amount: 0.01 },
      { to: 10000, amount: 0.008 },
      { to: 'inf', amount: 0.005 },
    ],
    billingMethod: 'usage_based',
    interval: 'month',
  },
})

Price Fields Reference

Common Patterns

Free Plan with Usage Limits

export const free = plan({
  id: 'free',
  name: 'Free',
  autoEnable: true,
  items: [
    item({
      featureId: messages.id,
      included: 5,
      reset: { interval: 'month' },
    }),
    item({
      featureId: seats.id,
      included: 1,
    }),
  ],
});

Paid Plan with Flat Fee + Overage

export const pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  items: [
    item({
      featureId: messages.id,
      included: 1000,
      reset: { interval: 'month' },
      price: {
        amount: 0.01,
        interval: 'month',
        billingMethod: 'usage_based',
      },
    }),
  ],
});

Per-Unit Pricing (e.g., per seat)

For any "per-X" pricing (like "$Y per seat"), use a base fee + unit allocation:

export const team = plan({
  id: 'team',
  name: 'Team',
  price: { amount: 10, interval: 'month' },
  items: [
    item({
      featureId: seats.id,
      included: 1,
      price: {
        amount: 10,
        interval: 'month',
        billingMethod: 'usage_based',
        billingUnits: 1,
      },
    }),
  ],
});

This creates: $10/month base price that includes 1 seat, then $10 per additional seat.

Plan with Free Trial

export const pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  freeTrial: {
    durationLength: 14,
    durationType: 'day',
    cardRequired: true,
  },
  items: [
    item({ featureId: messages.id, included: 1000, reset: { interval: 'month' } }),
    item({ featureId: sso.id }),
  ],
});

Add-on / Top-up (One-time Prepaid)

export const topUp = plan({
  id: 'top_up',
  name: 'Message Top-Up',
  addOn: true,
  items: [
    item({
      featureId: messages.id,
      price: {
        amount: 5,
        billingUnits: 100,
        billingMethod: 'prepaid',
      },
    }),
  ],
});

Annual Plan Variant

For annual variants, create a separate plan with annual price interval:

export const proAnnual = plan({
  id: 'pro_annual',
  name: 'Pro - Annual',
  group: 'pro',
  price: { amount: 192, interval: 'year' },
  items: [
    item({ featureId: messages.id, included: 1000, reset: { interval: 'month' } }),
  ],
});

Full Example

A complete config with a free plan, a paid plan with a trial, and a credits top-up add-on:

// autumn.config.ts
import { feature, item, plan } from 'atmn';

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

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

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

// Plans
export const free = plan({
  id: 'free',
  name: 'Free',
  autoEnable: true,
  items: [
    item({
      featureId: messages.id,
      included: 5,
      reset: { interval: 'month' },
    }),
    item({
      featureId: seats.id,
      included: 1,
    }),
  ],
});

export const pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  freeTrial: {
    durationLength: 14,
    durationType: 'day',
    cardRequired: true,
  },
  items: [
    item({
      featureId: messages.id,
      included: 1000,
      reset: { interval: 'month' },
    }),
    item({
      featureId: seats.id,
      included: 5,
      price: {
        amount: 10,
        interval: 'month',
        billingMethod: 'usage_based',
        billingUnits: 1,
      },
    }),
    item({
      featureId: sso.id,
    }),
  ],
});

export const topUp = plan({
  id: 'top_up',
  name: 'Message Top-Up',
  addOn: true,
  items: [
    item({
      featureId: messages.id,
      price: {
        amount: 5,
        billingUnits: 100,
        billingMethod: 'prepaid',
      },
    }),
  ],
});

Guidelines

Start Simple

• If the user describes more than 3 features, start with the 3 most important (prioritize metered features) and ask them to confirm before adding more
• Inform them you kept it simple to start with, but they can add more later

Disambiguate Pricing Model

• When the user mentions a price for a feature, ask whether it should be usage-based (pay as you go, billed at the end of the cycle) or prepaid (buy a fixed quantity upfront)
• Don't assume one or the other without asking

Don't Fabricate Capabilities

• If the user asks about pricing or functionality you're not sure Autumn supports, do NOT make it up or assume it can be done
• Point them to Discord (https://discord.gg/atmn) or docs (https://docs.useautumn.com/llms.txt) instead

Naming Conventions

• Feature and plan IDs should be lowercase with underscores (e.g., pro_plan, chat_messages)

Features vs Plan Items

• Features define WHAT can be tracked (e.g., "credits")
• Plan items define HOW a feature is granted in a plan (recurring, one-time, free, paid)
• Never create duplicate features for the same underlying resource
  • Example: "monthly tokens" and "one-time tokens" should be the SAME feature ("tokens"), referenced by different plan items with different intervals

Default Plans

• Never set autoEnable: true for plans with prices
• Default plans must be free

Enterprise Plans

• Ignore "Enterprise" plans with custom pricing in the config
• Custom plans can be created per-customer in the Autumn dashboard

Currency

• Currency can be changed in the Autumn dashboard under Developer > Stripe

Previewing and Pushing Changes

After updating autumn.config.ts:

1. Preview first: Run atmn preview to lint, validate and preview your plans. Show the output to the user so they can review the full configuration.
2. Get confirmation: Ask the user to review, edit, and confirm the preview output before pushing. Do NOT push until the user explicitly confirms.
3. Push: Once the user is happy, run atmn push to sync the configuration to Autumn.
4. Test in sandbox mode before going live. You can push to production with atmn push -p.

Resources

• Discord support: https://discord.gg/atmn (very responsive)
• Documentation: https://docs.useautumn.com
• LLM-friendly docs: https://docs.useautumn.com/llms.txt

Source: useautumn/autumn — distributed by TomeVault.