DOCSEARCHbyAlgolia
Submit Docs

Autumn Documentation

repository·dev·Indexed 25 days ago

https://github.com/useautumn/autumn

An open-source billing infrastructure layer that sits between Stripe and an application to simplify complex pricing models, including usage-based billing, credit systems, and seat-based plans. Includes a Python SDK (autumn-sdk) for managing customer billing, subscriptions, usage tracking, and AI token consumption, as well as tools for AI service integration via Autumn Leaf.

Tokens
235.5K
Snippets
398
Records
1.5K
Agent score
78%

What's inside Autumn

  1. Overview of Autumn Lakehouse

    dev

    The Autumn Lakehouse mirrors your entire Autumn dataset (customers, plans, subscriptions, invoices, balances, events, etc.) into your own data warehouse as Apache Iceberg tables. This allows you to perform analytics, BI reporting, and cohort analysis using SQL without needing to handle API pagination.

    Key Features

    • Direct SQL Access: Query data directly using ClickHouse (BigQuery support is planned).
    • Analytics Ready: Designed for joining Autumn's billing data against your own product data.
    • Automatic Schema Updates: New columns are added automatically without migrations.
    WARNING

    Available on request — The Autumn Lakehouse is provisioned per customer. Contact hey@useautumn.com to request access.

  2. Overview of Autumn

    dev

    Autumn is an open-source control layer designed for AI and SaaS monetization. It acts as a source of truth for billing and entitlements between your application and Stripe.

    Key capabilities include:

    • Subscription Management: Managing state, proration, and schedules.
    • Credit Ledgers: Real-time enforcement, grants, rollovers, and concurrency control.
    • Entitlements: Feature gating (boolean or metered) and seat-based allowances.
    • Billing Controls: Spend caps, auto top-ups, and overage handling.
    • Observability: Usage history and logs.

    Unlike traditional billing tools that focus on post-hoc invoicing, Autumn is a real-time system of record that allows you to query customer state (plans, entitlements, balances) inline to enforce access control and track usage.

  3. Overview of @autumn/agent-docs

    dev
    @autumn/agent-docs is a translation layer that converts Autumn's canonical documentation content (authored in apps/docs) into agent-facing surfaces. It does not hold its own reference content; instead, it acts as a machinery layer to transform existing documentation into specific formats like MCP resources or Agent Skills.

  4. Understand the `bun tw` µVM image scripts

    dev

    The bun tw scripts are designed to build and run the Autumn stack as native binaries on a Vercel Sandbox microVM (Amazon Linux 2023). These scripts are intended to run on the µVM, not on a local macOS development machine. They facilitate a cloud test swarm by allowing an orchestrator to fork sandboxes and invoke these scripts to boot workers.

    Key Environment & Runtime Details:

    • Target OS: Amazon Linux 2023 (dnf package manager).
    • Root Access: Full root + sudo available.
    • No Docker: These scripts run natively; they do not use a Docker daemon on the µVM.
    • Base Directory: TW_PREFIX=/opt/autumn-tw (contains pgdata/, dragonfly/, elasticmq/, bin/, and logs/).

  5. Understand the Autumn data model pipeline

    dev

    Autumn follows a structured pipeline to manage product access and billing:

    1. Features: The atomic building blocks (e.g., AI Credits). You define what parts of your product are controlled.
    2. Plans: Bundles of features with a base price (e.g., Pro Plan).
    3. Plan Items: The configuration of a feature within a plan. This defines if a feature is included for free or if it is priced (prepaid or usage-based).
    4. Subscriptions: Created when a plan is attached to a customer. Autumn manages the Stripe subscription and provisions balances automatically.
    5. Balances: The real-time tracking of what a customer has granted, used, and has remaining. Your application interacts with these to gate access and record usage.

  6. Understand the Autumn Object Graph

    dev

    Autumn acts as a database for application billing state, sitting as a layer above Stripe. While Stripe handles payments and invoicing, Autumn manages the provisioning of subscriptions, schedules, and billing objects.

    To model pricing effectively, understand the distinction between the Configuration Model (how you define your product) and the Runtime Model (how customers interact with it).

    Configuration Model (Setup)

    • Feature: The atomic unit being gated or billed. Referenced by Plan Items.
    • Plan: A package of items and pricing. Contains multiple Plan Items.
    • Plan Item: Connects a Feature to a specific price (usage-based or prepaid).

    Runtime Model (Customer State)

    • Customer: The top-level billing identity. Contains subscriptions, purchases, balances, flags, and billing_controls.
    • Entity: A sub-account or seat belonging to a Customer. It shares the same runtime shape (subscriptions, balances, etc.) but is scoped to the entity.
    • Subscription/Purchase: The result of attaching a Plan to a Customer or Entity via the --billing.attach operation.

  7. Understand Autumn's Fail-Open mechanism

    dev

    Autumn SDKs include a fail-open mechanism enabled by default. This prevents your application from crashing or blocking users if Autumn is unreachable due to network failures, timeouts, or 5XX server errors.

    When fail-open is active, the SDK returns safe default responses instead of throwing errors. Note that usage events may be lost during an outage, but user access is preserved.

  8. Understand the Pull View CLI UI

    dev
    The atmn pull command uses a card-based, interactive UI built with React Ink to provide a visual experience when pulling data from Autumn. The UI is structured into progressive stages: Header, Organization, Features, Plans, Files, and Done. It automatically detects if it is running in a TTY (interactive terminal) or a non-TTY environment (like CI/CD or an AI agent) and switches between the beautiful Ink UI and plain text output accordingly.

  9. Use the React + TypeScript + Vite + shadcn/ui template

    dev
    The apps/checkout directory serves as a template for initializing new projects using React, TypeScript, Vite, and shadcn/ui. This stack provides a modern development environment with type safety and pre-configured UI components.

  10. Understand Autumn Lakehouse balance tables

    dev

    The v2_3_balances and v2_3_breakdowns tables are denormalized snapshots of Autumn's read-time balance computations. They are not a standard relational schema and should be treated as columns representing source values rather than terms for naive arithmetic.

    Key distinction: The warehouse (ETL) aggregates over all entitlement rows ever held, whereas the API only aggregates active, current-cycle entitlements. To match API or dashboard figures, you must manually apply filters for active products, non-expired entitlements, and the current cycle.

  11. Understand Autumn and Stripe responsibilities

    dev

    Autumn and Stripe share responsibilities for managing your billing lifecycle. Autumn acts as the source of truth for customer state, pricing, features, and usage metering, while Stripe handles the actual movement of money, subscriptions, and payment processing.

    FeatureManaged byDetails
    Pricing and featuresAutumnDefine and update in Autumn dashboard or API
    Balances & credit ledgersAutumnTracked in real-time via /check and /track
    Usage meteringAutumnTracks usage internally, posts totals to Stripe at cycle end (if configured)
    Feature gatingAutumn/check evaluates access from Autumn's balances
    Subscriptions and paymentsStripeAutumn creates Stripe subscriptions and charges customers
    Invoices & receiptsStripeGenerated and delivered by Stripe
    Checkout pagesStripeKeep Stripe Checkout pages for payment method collection
    Refunds & disputesStripeIssue refunds directly in Stripe dashboard

    Note: Autumn syncs from Stripe automatically. If you update or cancel a subscription directly in the Stripe dashboard, Autumn will attempt to apply the same change to the corresponding customer state.

  12. Understand CTE Builder Query Strategies

    dev

    The CTE Builder uses a dual-strategy architecture to select the optimal SQL generation approach:

    1. Correlated Subquery Strategy (Default):

      • Uses nested subqueries to fetch data (e.g., SELECT *, (subquery) AS field).
      • Pros: Simple, predictable, works with any nesting depth, consistent performance.
      • Cons: One subquery per parent row per nested field.
      • Best for: Moderate result sets (100-500 rows) and modern PostgreSQL (12+).

    2. JOIN + GROUP BY Strategy (Future/Experimental):

      • Uses a single JOIN pass with aggregation.
      • Pros: Potentially faster for very large datasets or cold caches.
      • Cons: More complex SQL generation, requires careful NULL handling.
      • Status: Implemented but not yet enabled by default. See OPTIMIZATION_STATUS.md to enable.