Add-Ons

Add-ons are plans that can be purchased alongside a customer’s existing plan, rather than replacing it. They’re used for top-ups, extra feature packs, or supplementary services.

Example
A customer on the Pro plan can purchase a “Storage Add-On” for an extra 100GB/month, or a one-time “Credit Top-Up” of 500 credits.

Setting up

CLI
Dashboard

Set addOn: true on the plan:

autumn.config.ts

import { feature, item, plan } from 'atmn';

export const storage = feature({
  id: 'storage',
  name: 'Storage (GB)',
  type: 'metered',
  consumable: false,
});

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

export const storageAddOn = plan({
  id: 'storage_add_on',
  name: 'Extra Storage',
  addOn: true,
  price: { amount: 5, interval: 'month' },
  items: [
    item({
      featureId: storage.id,
      included: 100,
    }),
  ],
});

export const creditTopUp = plan({
  id: 'credit_top_up',
  name: 'Credit Top-Up',
  addOn: true,
  items: [
    item({
      featureId: credits.id,
      price: {
        amount: 10,
        billingUnits: 500,
        billingMethod: 'prepaid',
      },
    }),
  ],
});

Push changes with atmn push.

How add-ons work

Without the add-on flag, attaching a new plan replaces the customer’s current plan (within the same group). With the add-on flag:

The plan is added alongside the customer’s existing plans
Multiple add-ons can be active at the same time
Add-ons don’t participate in upgrade/downgrade logic

Balance stacking

When an add-on provides the same feature as the customer’s main plan, the balances stack. Each source is tracked separately in the breakdown array.

Example
A customer’s Pro plan grants 1,000 credits/month. They purchase a one-time top-up of 500 credits. Their total balance is 1,500 credits, tracked as two separate sources.

Autumn uses deduction order to consume shorter-interval balances first (monthly before lifetime).

Purchasing add-ons

Add-ons use the same checkout/attach flow as regular plans:

import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: "am_sk_..." });

const { data } = await autumn.checkout({
  customer_id: "user_123",
  plan_id: "storage_add_on",
});

from autumn_sdk import Autumn

autumn = Autumn("am_sk_...")

response = await autumn.checkout(
    customer_id="user_123",
    plan_id="storage_add_on",
)

curl -X POST "https://api.useautumn.com/v1/checkout" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "plan_id": "storage_add_on"
  }'

For prepaid add-ons (like a credit top-up), pass the quantity:

TypeScript

const { data } = await autumn.checkout({
  customer_id: "user_123",
  plan_id: "credit_top_up",
  options: [{
    feature_id: "credits",
    quantity: 1000,
  }],
});

Cancelling add-ons

Cancel an add-on using the same cancel flow:

await autumn.cancel({
  customer_id: "user_123",
  plan_id: "storage_add_on",
});

await autumn.cancel(
    customer_id="user_123",
    plan_id="storage_add_on",
)

curl -X POST "https://api.useautumn.com/v1/cancel" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "plan_id": "storage_add_on"
  }'

Common add-on patterns

Pattern	Configuration
Recurring add-on	`addOn: true`, recurring price (e.g., $5/month for extra storage)
One-time top-up	`addOn: true`, prepaid price, no base price
Feature pack	`addOn: true`, grants boolean or metered features

Getting Started

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Lakehouse

Setting up

How add-ons work

Balance stacking

Purchasing add-ons

Cancelling add-ons

Common add-on patterns

​Setting up

​How add-ons work

​Balance stacking

​Purchasing add-ons

​Cancelling add-ons

​Common add-on patterns

Setting up

How add-ons work

Balance stacking

Purchasing add-ons

Cancelling add-ons

Common add-on patterns