Skip to main content
Autumn uses Stripe to create subscriptions and charge customers. You define plans, features and pricing in Autumn, and Stripe objects (customers, products, prices, subscriptions, invoices) are created automatically as they’re needed. You never need to manually create or interact with these objects in Stripe. Autumn handles the full lifecycle, and owns the customer state.

​
Autumn and Stripe responsibilities

Autumn is the source of truth for a customer’s state and what they can do. Stripe handles subscriptions and payments.
Autumn syncs from Stripe automatically. If you update or cancel a subscription directly in the Stripe dashboard, Autumn will attempt to apply the same change to the corresponding customer state.

​
Connecting Stripe

There are three ways to connect your Stripe account to Autumn:
When disconnecting and reconnecting a different Stripe account, existing Stripe IDs on your plans become invalid. Autumn will recreate the products and prices in the new account when you attach it, but old customers and subscriptions will no longer be linked.

​
Currency

Currency is set at the organization level and defaults to usd. You can change it when connecting Stripe or from the developer settings page. All new Stripe prices are created in your configured currency. Changing the currency does not migrate existing subscriptions — those remain in the original currency. New prices and subscriptions going forward will use the updated currency.

​
How customers map

When you create a customer in Autumn, you pass your own user ID (from your auth system, database, or any unique identifier) as the customer_id. This is the only ID you need — there’s no separate “auth ID” concept. By default, a Stripe customer is not created when you create an Autumn customer. The Stripe customer is created lazily — the first time a billing operation needs one (attaching a plan, opening the billing portal, setting up a payment method, etc.). You can change this behavior:
  • Pass createInStripe: true to create the Stripe customer immediately when the Autumn customer is created
  • Pass stripeId: "cus_abc123" to link an existing Stripe customer instead of creating a new one
See Creating Customers for details. Once linked, the mapping is bidirectional:
  • Autumn → Stripe: the Stripe customer ID is stored on the Autumn customer
  • Stripe → Autumn: the Autumn customer ID is stored in the Stripe customer’s metadata

​
How products and prices map

The table below shows what maps to what:
In production, Stripe products and prices are lazily created — only on the first attach that uses them, not when you create or update a plan in Autumn. This means you can pre-map an Autumn plan to an existing Stripe product/price before the first attach, and Autumn will reuse it instead of creating a duplicate.

​
Fixed prices

Each fixed price on a plan maps 1:1 to a Stripe price, attached to the plan’s Stripe product.

​
Usage-based prices

Usage-based prices are more complex. For each priced feature, Autumn creates a separate Stripe product (named "Plan Name - Feature Name") with its own Stripe price. Depending on the billing model, Autumn may also create:
  • An empty placeholder price to anchor the subscription
  • A billing meter for in-arrear usage reporting
  • A prepaid price for upfront usage billing
These are all managed automatically — you don’t need to configure them.

​
Renaming in Stripe

You can rename products and update their descriptions directly in the Stripe dashboard for display purposes (e.g., on invoices or the customer portal). Autumn won’t overwrite these cosmetic changes.
Renaming in Stripe is purely cosmetic. The plan’s ID and configuration are still managed in Autumn. For structural changes (prices, features, billing model), always use Autumn.

​
Webhooks

Autumn automatically creates and manages webhook endpoints when you connect Stripe. You don’t need to configure these manually. Autumn listens for key Stripe events to keep state in sync:

​
Direct vs deferred execution

When you call billing.attach, Autumn takes one of two paths depending on whether the customer can be charged immediately: Direct (immediate): The customer already has a payment method. Autumn creates the Stripe subscription, charges the customer, and provisions balances — all in a single API call. Deferred (checkout): The customer doesn’t have a payment method, or the payment requires additional action (like 3DS). Autumn creates a Stripe Checkout Session (or returns a required_action), stores the pending billing plan, and completes everything when the webhook confirms payment. See Payment Flow for the full breakdown of redirect modes and checkout behavior.

​
What to do in Stripe directly

While Autumn manages most of the Stripe lifecycle, there are a few things you should handle in Stripe: