Skip to main content
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

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",
});
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",
});

​
Common add-on patterns

PatternConfiguration
Recurring add-onaddOn: true, recurring price (e.g., $5/month for extra storage)
One-time top-upaddOn: true, prepaid price, no base price
Feature packaddOn: true, grants boolean or metered features