Pending updates
Learn how to handle payment failures when updating subscriptions.
Updating a subscription generates a new invoice when:
- The subscription requires payment for the first time, such as the end of a trial period.
- The billing period changes.
- Changing the subscription causes a proration and
proration_
.behavior=always_ invoice
By default, updates are applied regardless of whether payment on the new invoice succeeds. If payment fails, rolling back the updates is a manual process. You need to create a new invoice, prorate items on the invoice, and then initiate payment again. However, with the pending updates feature, you can make changes to subscriptions only if payment succeeds on the new invoice.
Caution
Pending updates aren’t supported when the subscription’s collection_method is send_
or when bank debits are used as the payment method for the subscription.
Update the subscriptionServer-side
You can use pending updates with the update subscription, create subscription item, and update subscription item calls. When you make the update, set payment_
. The example below adds a new price to a subscription. Because proration_
, an invoice is created and payment is attempted when the update is made.
If payment succeeds, the subscription is updated. If payment fails, the Subscription
object that’s returned contains a pending_
hash with the changes:
{ "id": "sub_49ty4767H20z6a", "object": "subscription", "application_fee_percent": null, "pending_update": { "expires_at": 1571194285, "subscription_items": [ { "id": "si_09IkI4u3ZypJUk5onGUZpe8O", "price": "price_CBb6IXqvTLXp3f" } ] }, }
Handle failed paymentsClient-side
After making the update, check the pending_
hash on the subscription or listen for the customer.
event in your webhook. A populated pending_
hash means the payment failed and your subscription update isn’t applied.
Build logic to handle payment failures due to card declines and customer authentication requests:
- For card declines, attach a new payment method to the customer. Then use the pay endpoint to pay the invoice that the update generates.
- For customer authentication, follow the requires action flow.
A successful payment immediately applies the changes in the pending_
hash and updates the invoice to paid
.
If payment fails again, the pending_
hash remains on the subscription with the original expiry date and no changes are applied.
Supported attributes for pending updates 
Pending updates only support attributes that control proration behavior or generate new invoices.
The update subscription endpoint supports the following attributes:
expand
payment_
behavior proration_
behavior proration_
date billing_
cycle_ anchor items
price
quantity
trial_
end trial_
from_ plan add_
invoice_ items
The create subscription item and update subscription item endpoints support the following attributes:
expand
payment_
behavior proration_
behavior proration_
date price
quantity
Expired updates 
If you don’t take any action after an update fails, Stripe voids the invoice and discards the update after it expires.
A pending update’s expired_
time matches the first occurrence of either the trial end or the earliest items.current period end if either time is within 23 hours of the update request. Otherwise, the expiration is 23 hours from the update request.
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 
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. |
customer. | Receive notifications when pending updates expire or are automatically voided, and if needed, try the update request again. |
Pending updates and subscription schedules 
You can use both pending updates and subscription schedules to manage subscriptions. A schedule phase change discards a pending update and voids the associated invoice. 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 the pending update expires before payment, Stripe discards these usage records, which prevents any subsequent invoices from billing for them. 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, meaning you can’t bill for that usage.