Products and Plans

Understanding products, pricing plans, and how they work together in Autumn

Overview

In Autumn, Products represent the pricing plans that customers can subscribe to. Each product bundles together prices, entitlements, and features to create a complete monetization package.

Products are versioned, allowing you to iterate on pricing without affecting existing customers. When you update a product, a new version is created automatically.

Product Structure

A product consists of several key components:

type Product = {
  id: string;                    // User-facing identifier (e.g., "pro", "enterprise")
  internal_id: string;           // Internal database identifier
  name: string;                  // Display name (e.g., "Pro Plan")
  description: string | null;    // Optional description
  version: number;               // Version number for tracking changes
  
  // Organization
  org_id: string;                // Organization that owns this product
  env: "test" | "prod";         // Environment (test or production)
  
  // Categorization
  is_add_on: boolean;            // Whether this is an add-on product
  is_default: boolean;           // Whether this is a default product
  group: string;                 // Grouping for related products
  
  // External integration
  processor: {                   // Payment processor details
    type: "stripe";
    id: string;                  // Stripe product ID
  } | null;
  
  // Metadata
  created_at: number;
  archived: boolean;             // Soft delete flag
};

Product Types

Autumn supports several product patterns:

Subscription Plans

Recurring products with monthly, quarterly, or annual billing:

// Example: Monthly Pro Plan
{
  id: "pro_monthly",
  name: "Pro Plan (Monthly)",
  is_add_on: false,
  is_default: false,
  // Contains prices with interval: "month"
}

Add-ons

Supplementary products that can be attached to a base plan:

// Example: Extra storage add-on
{
  id: "extra_storage",
  name: "Additional Storage",
  is_add_on: true,
  is_default: false,
}

Free Plans

Products with zero-cost pricing, often used as default entry points:

// Example: Free tier
{
  id: "free",
  name: "Free Plan",
  is_add_on: false,
  is_default: true,  // Assigned to new customers
  group: "base",     // Grouped with other base plans
}

A product is considered “free” when all its prices have a total cost of zero.

One-off Products

Single-purchase products without recurring charges:

// Example: Credits pack purchase
{
  id: "credits_1000",
  name: "1,000 AI Credits",
  is_add_on: true,
  // Contains prices with interval: "one_off"
}

Product Versioning

When you modify a product, Autumn creates a new version while preserving the old one:

// Original version
{ id: "pro", version: 1, name: "Pro Plan", /* ... */ }

// After updating pricing
{ id: "pro", version: 2, name: "Pro Plan", /* ... */ }

Key points:

• Existing customers stay on their current version
• New customers get the latest version
• Each version has a unique internal_id but shares the same id
• You can migrate customers between versions using the migration API

Product Groups

The group field organizes related products:

// Base subscription tiers
{ id: "free", group: "base" }
{ id: "pro", group: "base" }
{ id: "enterprise", group: "base" }

// Add-ons
{ id: "extra_seats", group: "addons" }
{ id: "priority_support", group: "addons" }

Groups are useful for:

• Organizing products in your dashboard
• Defining upgrade/downgrade paths
• Managing default products per category

Full Product Object

When working with the API, you’ll often receive a FullProduct that includes all related data:

type FullProduct = Product & {
  prices: Price[];                      // All pricing configurations
  entitlements: Entitlement[];          // Feature access grants
  free_trial: FreeTrial | null;         // Optional free trial config
};

This bundled structure makes it easy to understand everything a product offers:

const proProduct: FullProduct = {
  id: "pro",
  name: "Pro Plan",
  version: 1,
  // ... other product fields
  
  prices: [
    {
      config: {
        type: "fixed",
        amount: 2900,        // $29.00
        interval: "month"
      }
    }
  ],
  
  entitlements: [
    {
      feature_id: "api_calls",
      allowance: 100000,
      allowance_type: "metered"
    },
    {
      feature_id: "advanced_analytics",
      allowance_type: "boolean"
    }
  ],
  
  free_trial: {
    interval: "day",
    interval_count: 14
  }
};

Creating Products

Products are typically created through the Autumn dashboard, but you can also use the API:

// Using the attach endpoint
const { attach } = useAutumn();

await attach({
  productId: "pro",  // Attaches the latest version of "pro"
});

See Pricing Models to learn about the different price types you can add to products.

Product Upgrade/Downgrade Logic

Autumn automatically determines whether moving between products is an upgrade or downgrade:

// Comparison factors (in order):
// 1. Free vs Paid: Any paid product > free product
// 2. Billing interval: Longer intervals rank higher (year > month > one_off)
// 3. Total price: Higher price = upgrade

// Examples:
isFreeProduct(freePlan.prices)        // true
isProductUpgrade({
  prices1: freePlan.prices,
  prices2: proPlan.prices
})                                     // true (free → paid)

isProductUpgrade({
  prices1: monthlyPlan.prices,
  prices2: annualPlan.prices  
})                                     // true (monthly → annual)

Autumn handles all the complexity of upgrades and downgrades, including proration, for you automatically.

Custom Products

You can create custom pricing for specific customers:

// Products can be marked as custom
{
  id: "enterprise_custom_acme",
  name: "Enterprise - Acme Corp",
  is_custom: true,  // Not shown in public pricing
  // ... custom pricing configuration
}

Custom products:

• Don’t appear in standard product listings
• Can have negotiated pricing
• Can combine features from multiple standard products
• Are tracked separately in analytics

Next Steps

• Learn about Pricing Models to understand different price types
• Explore Features to see how to control feature access
• Read about Customers to understand how products are assigned