Skip to main content
Recurring plans let you grant customers a fixed allowance of consumable features — like messages, credits, or API calls — that resets each billing period. Customers pay a base price at a regular interval (monthly, quarterly, annually), and receive a fresh grant of their included features at the start of each cycle.
Example
An AI writing tool offers a Pro plan at $20/month that grants 1,000 messages per month. When the billing period resets, the customer’s message balance is reset back to 1,000.

​
Setting up

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 pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  items: [
    item({
      featureId: messages.id,
      included: 1000,
      reset: { interval: 'month' },
    }),
  ],
});
Push changes with atmn push.

​
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" });
When a subscription is created, Autumn:
  1. Creates a Stripe subscription with the plan’s prices
  2. Grants the customer their included balances for each consumable feature
  3. Starts the billing cycle — balances reset automatically at the start of each period

​
Billing intervals

Plans support the following billing intervals:
IntervalDescription
weekBilled every week
monthBilled every month
quarterBilled every 3 months
semi_annualBilled every 6 months
yearBilled 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).

​
Billing interval vs reset interval

The billing interval (how often the customer is charged) and the reset interval (how often their feature balance replenishes) are configured independently. They don’t have to match.
Example
A plan billed at $200/year could grant 100 messages/month. The customer pays once a year, but their message balance resets to 100 every month.
This is useful when you want to offer an annual discount while still metering usage on a shorter cycle.

​
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

StatusDescription
activeSubscription is in good standing
trialingCustomer is in a free trial period
past_duePayment failed, needs attention
scheduledWill activate at end of current billing period (e.g., downgrade)
expiredSubscription has ended