Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

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.

post/v1/billing.preview_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.

subtotalnumber required

The total amount in cents before discounts and tax for the current billing period.

totalnumber required

The final amount in cents after discounts and tax for the current billing period.

currencystring required

The three-letter ISO currency code (e.g., 'usd').

expandstring[]

Expand the response with additional data.

redirect_to_checkoutboolean required

Whether the customer will be redirected to a checkout page if attach is called.

checkout_type'stripe_checkout' | 'autumn_checkout' nullable required

The type of checkout that will be used if the customer is redirected to a checkout page.

Example 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"
}