You're viewing the docs for Autumn's v2 API. You can find the previous API version here.
Billing
Balances
Webhook Events
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.billing.attach({
customerId: "cus_123",
planId: "pro_plan",
});{
"customer_id": "cus_123",
"payment_url": "https://checkout.stripe.com/..."
}
Attach
Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades.
Use this endpoint to subscribe a customer to a plan, upgrade/downgrade between plans, or add an add-on product.
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.billing.attach({
customerId: "cus_123",
planId: "pro_plan",
});{
"customer_id": "cus_123",
"payment_url": "https://checkout.stripe.com/..."
}
Documentation Index
Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
Use this file to discover all available pages before exploring further.
Common Use Cases
const response = await autumn.billing.attach({
customerId: "cus_123",
planId: "pro_plan",
});
if (response.paymentUrl) {
// Redirect customer to checkout
window.location.href = response.paymentUrl;
}
Stripe checkout session params
UsecheckoutSessionParams to pass additional data to the Stripe checkout session. Values you provide are deep-merged with Autumn’s internal parameters, so your fields are preserved alongside ones Autumn sets automatically (like trial_end or internal metadata).
This is useful for attaching custom metadata to the Stripe subscription created during checkout — for example, linking subscriptions to internal user IDs or tracking the source of the purchase.
Body Parameters
Response
{
"customer_id": "cus_123",
"payment_url": "https://checkout.stripe.com/..."
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
The ID of the customer to attach the plan to.
The ID of the plan.
The ID of the entity to attach the plan to.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
Show child attributes
Show child attributes
The version of the plan to attach.
Customize the plan to attach. Can override the price, items, free trial, or a combination.
Show child attributes
Show child attributes
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
Show child attributes
Show child attributes
How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
prorate_immediately, none Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.
always, if_required, never A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
Show child attributes
Show child attributes
URL to redirect to after successful checkout.
Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
Reset the billing cycle anchor immediately with 'now'.
When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
immediate, end_of_cycle Additional parameters to pass into the creation of the Stripe checkout session.
Show child attributes
Show child attributes
Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).
Show child attributes
Show child attributes
The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
Whether to carry over balances from the previous plan.
Show child attributes
Show child attributes
Whether to carry over usages from the previous plan.
Show child attributes
Show child attributes
Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn_' are reserved and will be stripped.
Show child attributes
Show child attributes
If true, skips any billing changes for the attach operation.
If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer_product is inserted before the customer completes the hosted form.
Response
OK
The ID of the customer.
URL to redirect the customer to complete payment. Null if no payment action is required.
The ID of the entity, if the plan was attached to an entity.
Invoice details if an invoice was created. Only present when a charge was made.
Show child attributes
Show child attributes
Details about any action required to complete the payment. Present when the payment could not be processed automatically.
Show child attributes
Show child attributes