Skip to main content
POST
/
v1
/
billing.preview_update
Typescript (SDK)
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.billing.previewUpdate({
  customerId: "cus_123",
  planId: "pro_plan",
  featureQuantities: [
    {
      featureId: "seats",
      quantity: 15,
    },
  ],
});
{
  "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

​
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.

​
entity_id
string

The ID of the entity to attach the plan to.

​
plan_id
string

The ID of the plan to update. Optional if subscription_id is provided, or if the customer has only one product.

​
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.

​
cancel_action
enum<string>

Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.

Available options:
cancel_immediately,
cancel_end_of_cycle,
uncancel
​
no_billing_changes
boolean

If true, the subscription is updated internally without applying billing changes in Stripe.

Response

200 - application/json

OK

​
customer_id
string
required

The ID of the customer.

​
line_items
object[]
required

List of line items for the current billing period.

​
subtotal
number
required

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

​
total
number
required

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

​
currency
string
required

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

​
incoming
object[]
required

Products or subscription changes being added or updated.

​
outgoing
object[]
required

Products or subscription changes being removed or ended.

​
intent
enum<string>
required
Available options:
update_plan,
update_quantity,
cancel_immediately,
cancel_end_of_cycle,
uncancel,
none
​
next_cycle
object

Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.

​
expand
string[]

Expand the response with additional data.