Pending updates reference

Supported attributes

Only certain attributes can be used to create a pending update. These attributes either control proration behavior or generate new invoices.

The supported attributes for the update subscription endpoint are:

• expand
• payment_behavior
• proration_behavior
• proration_date
• billing_cycle_anchor
• items
  • price
  • quantity
• trial_end
• trial_from_plan
• add_invoice_items

The supported attributes for the create subscription item and update subscription item endpoints are:

• expand
• payment_behavior
• proration_behavior
• proration_date
• price
• quantity

Pending updates lifecycle

If payment succeeds, the invoice is updated to paid and the changes are applied to the subscription immediately. If payment fails, the updated values are added to the pending_update hash on the Subscription object. The latest_invoice for the subscription refers to an unpaid invoice in an open status. The subscription will continue to cycle as if no update request was made.

There are two ways to handle payment failures. These are related to declines and customer authentication. After resolving these issues, payment is attempted again. If the payment succeeds, the changes are applied and the pending_update hash is cleared. If payment fails again, the pending_update hash remains on the subscription with the original expiry date and no changes are applied.

If you cancel a pending update, the pending_update hash is cleared and the associated changes are discarded.

Expiration

If you don’t take any action after an update fails, the invoice is voided and the pending update is discarded after the expired_at time on the pending_update has passed. This time is set to either the trial end time or the current period end, whichever comes first. If these times are greater than 23 hours from the time the update is made, the expired_at time is calculated to 23 hours after the update call was made.

Stripe also automatically voids the invoice and removes the pending update if any of the following occurs:

• The subscription reaches a billing threshold.
• A subscription schedule linked to the subscription transitions to a new phase.

Pending updates events

You can use webhooks to listen for the following events related to pending updates:

Pending updates and subscription schedules

Pending updates and subscription schedules can both be used to manage subscriptions. If a pending update exists when a schedule changes phases, the pending update is discarded and the associated invoice is voided before the phase transition occurs. You can retry the update request after the phase transition if needed.

Usage records

If a subscription includes metered items, Stripe bills any outstanding usage records on the pending update invoice. However, if payment for the pending update doesn’t occur before the expiry date, Stripe discards these usage records, which prevents billing on the subsequent invoice. Additionally, if the pending update removes a metered price, Stripe disregards any usage reported between the pending update’s creation and the resulting invoice’s payment, excluding it from all invoices.