Pending updates reference
Learn more about the pending updates feature.
Supported attributes![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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_
hash on the Subscription
object. The latest_
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_
hash is cleared. If payment fails again, the pending_
hash remains on the subscription with the original expiry date and no changes are applied.
If you cancel a pending update, the pending_
hash is cleared and the associated changes are discarded.
Expiration![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
If you don’t take any action after an update fails, the invoice is voided and the pending update is discarded after the expired_
time on the pending_
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_
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can use webhooks to listen for the following events related to pending updates:
Event | Purpose |
---|---|
customer. | Receive notifications for subscriptions, checking for the pending_ hash and resolving payment failures if needed. |
customer. | Receive notifications when pending updates are applied so that you can take further actions like upgrading, downgrading, provisioning or deprovisioning services, and so on. |
customer. | Receive notifications when pending updates expire or are automatically voided, and if needed, try the update request again. |
Pending updates and subscription schedules![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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.