import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.billing.previewAttach({
customerId: "cus_123",
planId: "pro_plan",
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.billing.preview_attach(
customer_id="cus_123",
plan_id="pro_plan",
redirect_mode="if_required",
)curl --request POST \
--url https://api.useautumn.com/v1/billing.preview_attach \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "cus_123",
"plan_id": "pro_plan"
}
'{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": 20,
"total": 20,
"currency": "usd"
}
Preview Attach
Previews the billing changes that would occur when attaching a plan, without actually making any changes.
Use this endpoint to show customers what they will be charged before confirming a subscription change.
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.billing.previewAttach({
customerId: "cus_123",
planId: "pro_plan",
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.billing.preview_attach(
customer_id="cus_123",
plan_id="pro_plan",
redirect_mode="if_required",
)curl --request POST \
--url https://api.useautumn.com/v1/billing.preview_attach \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "cus_123",
"plan_id": "pro_plan"
}
'{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": 20,
"total": 20,
"currency": "usd"
}
Body Parameters
Response
{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": 20,
"total": 20,
"currency": "usd"
}
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.
Free trial for this plan. A shorthand for customize.free_trial, which takes precedence when both are given.
Show child attributes
Show child attributes
Customize the plan to attach. Can override the price, items, licenses, 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 immediately with 'now', or schedule a reset at a future Unix timestamp in milliseconds.
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 Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.
0 <= x <= 9007199254740991Unix timestamp in milliseconds for when the attached plan should end.
0 <= x <= 9007199254740991Additional parameters to pass into the creation of the Stripe checkout session.
Show child attributes
Show child attributes
If true, returns an Autumn-hosted checkout link that can create a fresh Stripe checkout session when opened.
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
Seat quantities for the plan's licenses, keyed by license 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. Set it here rather than on invoice_mode, which only covers the invoice-unpaid case.
Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.
Currency to bill this attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and the plan must offer a paid price in it. Defaults to the customer's currency, then the org default.
Plan IDs to expire on the customer as part of this attach. Each must be an active plan billed on the same subscription as the attach (or a free plan); plans on a separate subscription are rejected.
Response
OK
The ID of the customer.
Show child attributes
Show child attributes
The total amount before discounts and tax for the current billing period.
The final amount after discounts and tax for the current billing period.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
Products or subscription changes being added or updated.
Show child attributes
Show child attributes
Products or subscription changes being removed or ended.
Show child attributes
Show child attributes
Whether the customer will be redirected to a checkout page if attach is called.
The type of checkout that will be used if the customer is redirected to a checkout page.
stripe_checkout, autumn_checkout True when this change clears the customer's usage balances, so the approver can see usage will reset.
Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
Show child attributes
Show child attributes
Expand the response with additional data.
Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location.
Show child attributes
Show child attributes
Stripe customer invoice credits preview.
Show child attributes
Show child attributes