Recurring Plans

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

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 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.

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 consumable features to the plan — set grant amounts and reset intervals. These will be granted to the customer each billing period once they subscribe.
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" });

import { Autumn } from "autumn-js";

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

const response = await autumn.billing.attach({
  customerId: "user_123",
  planId: "pro",
  redirectMode: "always",
});

// Redirect customer to complete payment or confirm plan change
redirect(response.paymentUrl);

import asyncio
from autumn_sdk import Autumn

autumn = Autumn("am_sk_...")

async def main():
    response = await autumn.billing.attach(
        customer_id="user_123",
        plan_id="pro",
        redirect_mode="always",
    )

    # Redirect customer to response.payment_url

asyncio.run(main())

curl -X POST "https://api.useautumn.com/v1/attach" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "plan_id": "pro",
    "redirect_mode": "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
        }
      ]
    }
  }
}

When a subscription is created, Autumn:

Creates a Stripe subscription with the plan’s prices
Grants the customer their included balances for each consumable feature
Starts the billing cycle — balances reset automatically at the start of each period

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).

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

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

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Lakehouse

Recurring Plans

Setting up

Attaching a subscription

Billing intervals

Billing interval vs reset interval

Managing subscriptions

Subscription statuses

​Setting up

​Attaching a subscription

​Billing intervals

​Billing interval vs reset interval

​Managing subscriptions

​Subscription statuses

Setting up

Attaching a subscription

Billing intervals

Billing interval vs reset interval

Managing subscriptions

Subscription statuses