Preview Update
Previews the billing changes that would occur when updating a subscription, without actually making any changes.
Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications.
Body Parameters
Response
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
The ID of the customer to attach the plan to.
The ID of the entity to attach the plan to.
The ID of the plan to update. Optional if subscription_id is provided, or if the customer has only one product.
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.
The version of the plan to attach.
Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.
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.
How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
prorate_immediately, none 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.
always, if_required, never 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.
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
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.
cancel_immediately, cancel_end_of_cycle, uncancel Reset the billing cycle anchor immediately with 'now'
If true, the subscription is updated internally without applying billing changes in Stripe.
Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.
prorated, full Controls whether balances should be recalculated during the subscription update.
Whether to carry over usages from the previous plan.
Total seat quantities (inclusive of the license's included count) per license plan offered by this plan. Licenses not listed keep their current paid quantity.
Response
OK
The ID of the customer.
List of line items for the current billing period.
The total amount in cents before discounts and tax for the current billing period.
The final amount in cents after discounts and tax for the current billing period.
The three-letter ISO currency code (e.g., 'usd').
Products or subscription changes being added or updated.
Products or subscription changes being removed or ended.
update_plan, update_quantity, cancel_immediately, cancel_end_of_cycle, uncancel, none Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
Expand the response with additional data.
Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location.
Stripe customer invoice credits preview.