Modify subscriptions

You can modify active subscriptions without canceling and recreating them. You can also set up the customer portal to let customers manage their own subscriptions directly. The use cases below cover each type of change. See Billing updates for how modifications affect invoices and prorations.

Use cases

Billing updates

Not all subscription changes affect billing or generate prorations:

• Billing-related updates create prorations and can generate invoices. These include changing prices, quantities, billing periods, or adding or removing subscription items.
• Non-billing updates apply immediately without prorations. These include updating metadata, payment methods, tax settings, or applying or removing discounts.

For changes that automatically create a new subscription invoice, use pending updates so that the updates are only applied if the new invoice is successfully paid.

To see billing impacts before making changes, preview prorations.

Configuration updates

Configuration updates, like metadata and payment methods, don’t generate invoices with proration_behavior=always_invoice because they don’t change the amount owed for the current billing period. For a complete list, see What doesn’t trigger prorations.

Discounts

Updating only coupons or promotion codes doesn’t create proration invoice items. The new discount applies to the next invoice.

However, if you combine a non-prorating discount change with a proration-triggering update in the same API call (for example, changing an item quantity and modifying a discount), Stripe calculates the proration using the updated discount state. See Discount changes and prorations for details.