Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

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.

post/v1/billing.attach

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer to attach the plan to.

entity_idstring

The ID of the entity to attach the plan to.

plan_idstring required

The ID of the plan.

versionnumber

The version of the plan to attach.

proration_behavior'prorate_immediately' | 'none'

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

redirect_mode'always' | 'if_required' | 'never'

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.

subscription_idstring

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.

success_urlstring

URL to redirect to after successful checkout.

new_billing_subscriptionboolean

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

billing_cycle_anchor'now'

Reset the billing cycle anchor immediately with 'now'.

plan_schedule'immediate' | 'end_of_cycle'

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.

starts_atinteger

Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.

ends_atinteger

Unix timestamp in milliseconds for when the attached plan should end.

checkout_session_paramsobject

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

long_lived_checkoutboolean

If true, returns an Autumn-hosted checkout link that can create a fresh Stripe checkout session when opened.

processor_subscription_idstring

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

metadataobject

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.

no_billing_changesboolean

If true, skips any billing changes for the attach operation.

enable_plan_immediatelyboolean

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.

tax_rate_idstring

Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.

currencystring

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.

Example request

{
  "customer_id": "cus_123",
  "plan_id": "pro_plan"
}

Response

OK

customer_idstring required

The ID of the customer.

entity_idstring

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

payment_urlstring nullable required

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

Example response

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