Recurring Plans

Subscriptions are the most common way to charge customers on a recurring basis. A subscription plan has a fixed base price that customers pay at a regular interval (monthly, quarterly, annually), and can include features with usage limits or additional usage-based charges.

Example
A project management tool offers a Pro plan at $20/month that includes 10 seats, 50GB storage, and SSO access.

Setting up

CLI
Dashboard

Define a recurring plan in your autumn.config.ts:

autumn.config.ts

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

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

export const sso = feature({
  id: 'sso',
  name: 'SSO',
  type: 'boolean',
});

export const pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  items: [
    item({
      featureId: messages.id,
      included: 1000,
      reset: { interval: 'month' },
    }),
    item({
      featureId: sso.id,
    }),
  ],
});

Push changes with atmn push.

Navigate to Plans in the Autumn dashboard
Click Create Plan
Set a name and ID for the plan (e.g., “Pro”, pro)
Under Price, set the amount and select a billing interval (month, quarter, semi_annual, or year)
Add features to the plan — set grant amounts, reset intervals, and prices as needed. These will be granted to the customer once they purchase the plan.
Save your changes

Attaching a subscription

Use billing.attach to attach a subscription to a customer. With redirectMode: "always", a checkout URL is always returned for the customer to complete payment or confirm the plan change.

import { useCustomer } from "autumn-js/react";

const { attach } = useCustomer();

await attach({ planId: "pro", redirectMode: "always" });

Show customer object after attaching

{
  "id": "user_123",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "createdAt": 1771409161016,
  "fingerprint": null,
  "stripeId": "cus_U0BKxpq1mFhuJO",
  "env": "sandbox",
  "metadata": {},
  "sendEmailReceipts": false,
  "billingControls": {
    "autoTopups": []
  },
  "subscriptions": [
    {
      "planId": "pro",
      "autoEnable": false,
      "addOn": false,
      "status": "active",
      "pastDue": false,
      "canceledAt": null,
      "expiresAt": null,
      "trialEndsAt": null,
      "startedAt": 1771431921437,
      "currentPeriodStart": 1771431921437,
      "currentPeriodEnd": 1773851121437,
      "quantity": 1
    }
  ],
  "purchases": [],
  "balances": {
    "messages": {
      "featureId": "messages",
      "granted": 1000,
      "remaining": 1000,
      "usage": 0,
      "unlimited": false,
      "overageAllowed": false,
      "maxPurchase": null,
      "nextResetAt": 1773851121437,
      "breakdown": [
        {
          "id": "cus_ent_abc123",
          "planId": "pro",
          "includedGrant": 1000,
          "prepaidGrant": 0,
          "remaining": 1000,
          "usage": 0,
          "unlimited": false,
          "reset": {
            "interval": "month",
            "resetsAt": 1773851121437
          },
          "price": null,
          "expiresAt": null
        }
      ]
    },
    "sso": {
      "featureId": "sso",
      "granted": 1,
      "remaining": 1,
      "usage": 0,
      "unlimited": false,
      "overageAllowed": false,
      "maxPurchase": null,
      "nextResetAt": null,
      "breakdown": [
        {
          "id": "cus_ent_def456",
          "planId": "pro",
          "includedGrant": 1,
          "prepaidGrant": 0,
          "remaining": 1,
          "usage": 0,
          "unlimited": false,
          "reset": null,
          "price": null,
          "expiresAt": null
        }
      ]
    }
  }
}

When a subscription is created, Autumn:

Creates a Stripe subscription with the plan’s prices
Provisions balances for each feature in the plan
Starts the billing cycle based on the plan’s interval

Billing intervals

Plans support the following billing intervals:

Interval	Description
`week`	Billed every week
`month`	Billed every month
`quarter`	Billed every 3 months
`semi_annual`	Billed every 6 months
`year`	Billed annually

You can create a separate plan for each interval you want to support. For example, if you want to support monthly and annual plans, you can create a pro_monthly plan and a pro_annual plan. You can also configure a custom interval_count to charge at non-standard intervals (e.g., every 2 months).

Managing subscriptions

Once a customer has an active subscription, you can manage upgrades, downgrades, and cancellations. See Managing Subscriptions for details on:

Upgrades — prorated charges for switching to a higher-priced plan
Downgrades — scheduled at end of billing period
Cancellations — immediate or end-of-period

Subscription statuses

Status	Description
`active`	Subscription is in good standing
`trialing`	Customer is in a free trial period
`past_due`	Payment failed, needs attention
`scheduled`	Will activate at end of current billing period (e.g., downgrade)
`expired`	Subscription has ended

Getting Started

Concepts

Modelling Pricing

Billing & Subscriptions

Customers

Additional Resources

Recurring Plans

Setting up

Attaching a subscription

Billing intervals

Managing subscriptions

Subscription statuses

Getting Started

Concepts

Modelling Pricing

Billing & Subscriptions

Customers

Additional Resources

​Setting up

​Attaching a subscription

​Billing intervals

​Managing subscriptions

​Subscription statuses

Setting up

Attaching a subscription

Billing intervals

Managing subscriptions

Subscription statuses