Pending updates reference

Learn more about the pending updates feature.

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.


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:

Event Purpose
customer.subscription.updated Receive notifications for subscriptions, checking for the pending_updates hash and resolving payment failures if needed.
customer.subscription.pending_update_applied Receive notifications when pending updates are applied so that you can take further actions like upgrading, downgrading, provisioning or deprovisioning services, etc.
customer.subscription.pending_update_expired Receive notifications when pending updates expire or are automatically voided, and if needed, try the update request again.

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.

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.