Skip to main content
POST
/
v1
/
billing.attach
Typescript (SDK)
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/..."
}
The attach endpoint subscribes a customer to a plan. It handles new subscriptions, upgrades, and downgrades automatically. For modifying an existing subscription (like changing quantities or canceling), use update instead.

​
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;
}

​
Body Parameters

​
Response

{
  "customer_id": "cus_123",
  "payment_url": "https://checkout.stripe.com/..."
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-api-version
string
default:2.1
required

Body

application/json
​
customer_id
string
required

The ID of the customer to attach the plan to.

​
plan_id
string
required

The ID of the plan.

​
entity_id
string

The ID of the entity to attach the plan to.

​
feature_quantities
FeatureQuantity · object[]

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.

​
version
number

The version of the plan to attach.

​
customize
object

Customize the plan to attach. Can override the price, items, free trial, or a combination.

​
invoice_mode
object

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.

​
proration_behavior
enum<string>

How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.

Available options:
prorate_immediately,
none
​
redirect_mode
enum<string>
default:if_required

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.

Available options:
always,
if_required,
never
​
subscription_id
string

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.

​
discounts
AttachDiscount · object[]

List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.

​
success_url
string

URL to redirect to after successful checkout.

​
new_billing_subscription
boolean

Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.

​
plan_schedule
enum<string>

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.

Available options:
immediate,
end_of_cycle
​
checkout_session_params
object

Additional parameters to pass into the creation of the Stripe checkout session.

​
custom_line_items
object[]

Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).

​
processor_subscription_id
string

The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.

​
carry_over_balances
object

Whether to carry over balances from the previous plan.

​
carry_over_usages
object

Whether to carry over usages from the previous plan.

Response

200 - application/json

OK

​
customer_id
string
required

The ID of the customer.

​
payment_url
string | null
required

URL to redirect the customer to complete payment. Null if no payment action is required.

​
entity_id
string

The ID of the entity, if the plan was attached to an entity.

​
invoice
object

Invoice details if an invoice was created. Only present when a charge was made.

​
required_action
object

Details about any action required to complete the payment. Present when the payment could not be processed automatically.