1. Decide whether payment should gate the change
An accepted update request is not the same as a paid upgrade. Stripe says its default behavior applies subscription updates regardless of whether payment on the new invoice succeeds; pending updates instead let the change depend on successful payment.[1] For an application that sells a higher service tier, that distinction determines when the application should grant the new entitlement.
Start by identifying the subscription, its existing item and the proposed price or quantity. Record the current entitlement separately from the requested entitlement. This is an editorial implementation recommendation: support staff should be able to explain what is active now, what is being requested and which invoice must be paid, without interpreting a request log as an account-state change.
2. Confirm that this request qualifies
The documented prerequisites include collection_method=charge_automatically and a payment method on Stripe’s supported list. Pending updates are available for updating subscriptions and creating or updating subscription items; the request uses payment_behavior=pending_if_incomplete. The documentation’s example also sets proration_behavior=always_invoice so an invoice is created and payment attempted.[1] Check current eligibility for the actual account rather than treating the list as worldwide availability.
Not every edit produces a payment-gated update. Stripe lists payment-method, tax and retry configuration changes, billing threshold adjustments, cancel_at_period_end=true and one-time add_invoice_items among changes that do not themselves trigger pending updates.[1] Do not use this mechanism as a universal transaction wrapper around every subscription setting. Review the supported attributes before combining unrelated edits.
3. Read the resulting state before granting access
If payment succeeds, Stripe applies the change. If it fails, the returned Subscription contains a pending_update hash; after the request, inspect that hash or react to customer.subscription.updated. A populated hash means the subscription update has not been applied.[1] In your user interface, describe this as an upgrade awaiting payment rather than a completed upgrade with a background billing warning.
For a card decline, the documented recovery path is to attach a new payment method and pay the invoice generated by the update. For authentication, follow the requires-action flow. Successful payment applies the pending changes and marks the invoice paid; another failure leaves the pending update with its original expiry.[1] A retry is therefore not an automatic extension of the customer’s deadline.
4. Treat expiry as a state transition, not a countdown promise
Stripe voids the invoice and discards the update when it expires. The documentation describes an expiry at the earlier trial end or earliest item period end if that boundary is within 23 hours; otherwise the window is 23 hours from the update request.[1] Use the actual returned pending_update.expires_at value for operational displays, rather than manufacturing a fresh 23-hour window whenever a customer revisits the page.
A billing threshold or a linked subscription schedule moving to another phase can also void the invoice and remove the pending update. A schedule transition requires a new update request afterward if the change is still wanted.[1] Before telling a customer to retry an old invoice, retrieve the subscription and invoice again. A stale payment link should not be your source of truth for whether that upgrade remains available.
5. Cancel or replace deliberately
To cancel a pending update, Stripe instructs you to void its invoice, using the subscription’s latest invoice reference to locate it. Updating a pending change with new values voids the previous invoice and creates another; a failed payment on that replacement produces a new pending update and expiry.[1] Keep the superseded invoice ID in your support record so two requests are not mistaken for two independent purchases.
Metered items need special care: Stripe states that outstanding usage can be billed on the pending-update invoice and discarded if that update expires before payment. Removing a metered price has additional usage-treatment rules, including a flexible-billing exception.[1] This guide does not propose a generic metered upgrade recipe. Route those cases to the billing owner before selecting cancellation or replacement.
6. Build a small recovery checklist
Recommended decision order: retrieve the current subscription; confirm the desired change still exists; identify the associated invoice; compare the returned expiry with the current time; then choose authentication, payment-method replacement, deliberate cancellation or a new request. Keep the existing entitlement until the applied state is confirmed. These are operational controls, not claims that Stripe automatically manages your application’s access system.
Stripe documents customer.subscription.pending_update_applied for downstream provisioning work and customer.subscription.pending_update_expired for expiry or automatic voiding.[1] Test an immediate success, decline, authentication challenge, repeated failure, schedule transition and expired request in your own test environment. Save subscription and invoice IDs, requested item values and observed states. No live payment or account test was performed for this article.
Sources and dates
Official Stripe documentation in English. No publication or update date is stated; retrieved and checked on 2026-09-21. The retrieval date is not a source publication date. This is editorial research, not a PayIn feature claim, account eligibility check, or legal advice.
- [1] Pending updates · Checked 2026-09-21; source date not stated.