---
name: autumn-concepts
description: Understanding Autumn's billing objects before acting on them — what a plan version is and what active means, when a trial starts or ends billing, how entity- and seat-scoped subscriptions differ from the customer's own, what a customize diff actually changes, and how caps, overage, and top-ups behave. Load before versioning, editing, or drafting a plan, or when a customer's state does not match the plain reading of their plan.
---

# Concepts

Autumn is a database for your application billing state: features, plans, customers, subscriptions, purchases, balances, flags, and billing controls. It helps you iterate on pricing, manage credit access and usage, control overage, and keep billing behavior connected to product access.

Autumn is a layer above Stripe; Stripe still handles subscription management, invoicing, and payment processing. Autumn provisions and updates Stripe subscriptions, schedules, invoices, and related billing objects for you.

## Object graph

```txt
Organization
- features[] -> Feature
- plans[] -> Plan
- customers[] -> Customer

Configuration model:
Feature
- referenced by -> Plan Item
- credit_system type: maps actions to credit costs (flat or tiered)

Plan
- items[] -> Plan Item
  - feature_id -> Feature
  - optional price -> usage_based or prepaid feature price
- price -> base recurring or one-off price
- versions[] -> parallel definitions of this plan; ONE is active
- variants[] -> Plan (a derived plan storing only its differences)
- licenses[] -> Plan (a seat plan this plan hands out per seat)
- aliases -> old plan ids that still resolve after a rename

Plan Item
- feature_id -> Feature
- optional price -> usage_based or prepaid feature price
- pooled? -> entity grants combine into one shared customer balance

Runtime model:
Customer
- subscriptions[] -> Subscription -> Plan (a specific version of it)
- purchases[] -> Purchase -> Plan
- balances[feature_id] -> Balance -> Feature
  - pooled balance: fed by entity grants, spent by any entity
  - rollover, expiry, usage windows live here
- licenses[] -> CustomerLicense -> seats granted / in use / remaining
- flags[feature_id] -> Flag -> Feature
- billing_controls -> customer-level usage controls
- entities[] -> Entity -> same runtime shape scoped under Customer

Entity
- belongs to -> Customer
- subscriptions[] -> Subscription -> Plan
- purchases[] -> Purchase -> Plan
- balances[feature_id] -> Balance -> Feature
- flags[feature_id] -> Flag -> Feature
- license assignment -> holds one seat from the customer's pool

From config to customer state:
Plan + Customer --billing.attach--> Subscription or Purchase
Plan + Customer + entity_id --billing.attach--> Entity-scoped Subscription or Purchase
Parent plan's licenses --licenses.attach--> seat assigned to an Entity
Subscription/Purchase -> Balance or Flag provisioning
```

Two relationships changed recently — worth stating plainly because older docs describe the old way:

**Versions are groups of customers, not history.** A plan's versions used to be numbered steps in time, and the newest was always live. Now each version is a definition that some group of customers lives on, and exactly one is **active** — the one attach uses when no version is named. Which changes are edits and which are new versions, drafts, and how customers move: the plan definition below.

**Plans connect to other plans.** A plan can have variants (an annual twin storing only its differences), and it can offer licenses (a small seat plan it hands out per seat). So plans form a graph, not a flat list.

Use these definitions as the mental model when designing or changing Autumn
pricing. Reason in terms of features, plans, plan items, customers/entities, and
billing controls before writing any config or calling the API — most modeling
mistakes come from conflating a feature with a plan item, or a plan-level price
with a per-feature price.

## Definitions

Load the matching definition when reasoning about that object.

For defining a feature — the atomic unit Autumn gates, tracks, or bills, and its types, read `references/feature.md`.

For defining a plan — the attachable package of items and pricing, read `references/plan.md`.

For modeling plan items, or when you need concrete API request-body examples (included usage, prepaid, usage-based, tiers), read `references/plan-items.md`.

For using customize, reading plan update previews, or representing a small diff from a base plan, read `references/customize.md`.

For reasoning about free trials and when billing begins, read `references/trials.md`.

For distinguishing a customer from an entity (seats, sub-accounts) and their runtime billing state, read `references/customer-entity.md`.

For reasoning about billing controls — runtime caps, alerts, overage, and top-ups, read `references/billing-controls.md`.

For reasoning about licenses — seat plans a parent plan hands out, seat pools, assigning and releasing seats, read `references/licenses.md`.