Preview Multi Update

Previews the billing changes of a multi-plan update without making any changes. Returns one core preview per affected subscription.

Use this endpoint to show customers the credits and next-cycle changes of canceling multiple plans before confirming.

POST /v1/billing.preview_multi_update

Typescript (SDK)

TypeScript

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.billing.previewMultiUpdate({
  customerId: "cus_123",
  updates: [
    {
      planId: "pro_plan",
      cancelAction: "cancel_immediately",
    },
    {
      planId: "addon_seats",
      cancelAction: "cancel_immediately",
    },
  ],
});

200

{
  "customer_id": "cus_123",
  "currency": "usd",
  "total": -40,
  "subscriptions": [
    {
      "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",
      "plan_ids": [
        "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",
      "plan_ids": [
        "addon_seats"
      ]
    }
  ]
}

Body Parameters

Response

200

{
  "customer_id": "cus_123",
  "currency": "usd",
  "total": -40,
  "subscriptions": [
    {
      "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",
      "plan_ids": [
        "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",
      "plan_ids": [
        "addon_seats"
      ]
    }
  ]
}

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.4.0 · required

Body

application/json

customer_id · string · required

The ID of the customer to update plans for.

updates · object[] · required

The list of plan updates to apply to the customer.

Minimum array length: 1

Show child attributes

entity_id · string

The ID of the entity to update plans for. Individual updates can override this with their own entity_id.

refund_last_payment · enum<string>

Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.

Available options: prorated, full

subscription_params · SubscriptionParams · object

Additional parameters to pass into the Stripe subscription update or cancel call.

Show child attributes

Response

200 - application/json

OK

customer_id · string · required

The ID of the customer the preview applies to.

currency · string · required

The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).

total · number · required

The combined amount due today across all subscriptions (sum of subscriptions[].total).

subscriptions · object[] · required

One preview per affected Stripe subscription. Updates to plans without a subscription (free plans) produce no entry.

Show child attributes