Skip to main content
Attaching a plan to a customer will:
  • Grant the customer access to the features in the plan
  • If the plan has prices, generate a checkout URL for payment

​
Basic Usage

Call billing.attach to attach a plan to a customer. This always returns a paymentUrl that the customer should be redirected to. 
import { Autumn } from "autumn-js";

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

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

// Redirect customer to complete payment or confirm plan change
redirect(response.paymentUrl);
Default behavior:
  • New subscriptions: paymentUrl points to Stripe Checkout for payment collection
  • Plan changes (upgrades/downgrades): paymentUrl points to Autumn Checkout where the customer can review prorations before confirming
This handles any plan change scenario: new subscriptions, upgrades, downgrades, add-ons, and renewals.
  • Upgrades happen immediately with prorated charges
  • Downgrades are scheduled for the end of the current billing cycle

​
Building Your Own Checkout UI

Autumn’s checkout page is designed to get you off the ground quickly, but often you’ll want full control over the styling and user experience. For plan changes, you can build your own checkout UI using a two-step flow:

​
Step 1: Preview the change

Call billing.previewAttach to see exactly what will be charged before making any changes. This returns line items, totals, and next cycle information that you can display in your own UI. 
const preview = await autumn.billing.previewAttach({
  customerId: "user_123",
  planId: "pro",
});

// Display to user:
// - preview.lineItems (array of charges/credits)
// - preview.total (amount in cents)
// - preview.currency (e.g., "usd")
// - preview.nextCycle (next billing cycle info)

​
Step 2: Execute the change

Once the customer confirms, call billing.attach with redirectMode: "if_required". This will:
  • Charge the customer automatically if they have a payment method on file
  • Return a Stripe Checkout URL only if no payment method exists (for new customers)
const response = await autumn.billing.attach({
  customerId: "user_123",
  planId: "pro",
  redirectMode: "if_required",
});

if (response.paymentUrl) {
  // No payment method on file — redirect to Stripe Checkout
  redirect(response.paymentUrl);
} else {
  // Plan attached and charged successfully
  showSuccessMessage();
}