Stripe Pending Update

What the hash holds, and how long it lives

The pending update itself is small. It carries an expiry timestamp and the changes that are waiting, which in the ordinary case is the subscription items and their new prices. Stripe describes reading it directly: "After making the update, check the pending_update hash on the subscription or listen for the customer.subscription.updated event in your webhook. A populated pending_update hash means the payment failed and your subscription update isn’t applied."

The lifetime is short and worth knowing exactly, because it decides whether a problem is still fixable when somebody notices it. Stripe documents the expiry as matching "the first occurrence of either the trial end or the earliest items.current period end", if either falls within 23 hours of the update request. Otherwise it is 23 hours from the request itself.

After that, Stripe cleans up on its own: "If you don’t take any action after an update fails, Stripe voids the invoice and discards the update after it expires." Two other events do the same thing early. Reaching a billing threshold voids the invoice and removes the pending update, and so does a subscription schedule transitioning to a new phase.

So the window in which a failed upgrade can be rescued by getting the customer to pay is usually a single day. After that the invoice is void, the change is gone, and the customer is still on the plan they were on, having asked to change it.

Resolving one, cancelling one, and replacing one

A pending update resolves by payment. Stripe is specific about the effect: "A successful payment immediately applies the changes in the pending_update hash and updates the invoice to paid." So the fix for a card decline is the ordinary one, attach a working payment method and pay the invoice the update generated, and the subscription catches up by itself.

A second failure changes nothing. Stripe states that "if payment fails again, the pending_update hash remains on the subscription with the original expiry date and no changes are applied." The clock does not restart.

Cancelling is less obvious, and it is the detail most people miss: you cancel a pending update by voiding its invoice. There is no cancel endpoint for the update. Stripe directs you to the subscription’s latest_invoice attribute to find the invoice ID, then void that invoice.

Replacing one works the same way underneath. Requesting a new update with different values updates the hash, voids the invoice belonging to the previous pending update, and creates a new invoice for the new values. Payment of that new invoice applies the most recent change. Failure produces a new pending update with a fresh expiry that replaces the old one.

That void-and-recreate pattern is the part with bookkeeping consequences. A customer who changes their mind twice about an upgrade can leave a trail of voided invoices behind a single eventual change, all of them real Stripe invoices that were finalized before they were voided.

The four payment behaviours, side by side

Pending updates are one of four values on payment_behavior, and the reason to know all four is that they differ in what they write rather than in how they feel to a customer.

allow_incomplete is the default, and has been since the 2019-03-14 API version. Stripe transitions the subscription to past_due if payment fails, and retries the payment if retries are configured. The change is applied regardless.

default_incomplete transitions to past_due without attempting payment at all, and requires explicit confirmation of the invoice’s PaymentIntent. Stripe notes that the resulting invoice has auto_advance set to false, "so Stripe doesn’t automatically attempt payment, retry payment, or finalize the subscription."

error_if_incomplete returns an HTTP 402 and does not update the subscription. Nothing is written anywhere, which makes it the cleanest to reason about and the least forgiving: Stripe notes it does not support payments that require user action, such as 3DS authentication, because it returns an error rather than a PaymentIntent awaiting action.

pending_if_incomplete is the one this page is about. Stripe flags a real boundary on it: the behaviour "doesn’t support all attributes and payment methods". It requires collection_method to be charge_automatically, and the supported attributes are limited to those that control proration behaviour or generate invoices, which covers items, price, quantity, discounts, proration_behavior, billing_cycle_anchor, trial_end, coupons and promotion codes. Anything outside that list cannot be made conditional on payment.

Why the subscription and the invoice disagree

The practical problem a pending update creates is not an error. It is a disagreement between two sources of truth that are both behaving correctly.

The invoice is finalized. It carries the proration for the upgrade the customer asked for, at the new price, dated when they asked. Any report built from invoices counts that revenue. The subscription, meanwhile, still holds the old item at the old price, because that is exactly what the pending update was for.

This is a different situation from a subscription that simply failed to collect, and it is worth telling them apart when you are looking at a past_due list. Under allow_incomplete a past_due subscription has already changed, and the money is what is missing. Under pending_if_incomplete the money is missing and the change has not happened either, so a customer who was promised more seats does not have them.

The closing state matters more than the interim one. If the invoice is eventually paid, both sides agree and the only oddity is timing. If it expires, Stripe voids the invoice, and the revenue an invoice-based report counted in the interim comes back out. A period closed in the middle of that window, on invoice-derived figures, is a period that counted something later voided.

The practical guidance is narrow: when reconciling subscription changes to invoices, treat a finalized unpaid invoice attached to a pending update as provisional, and check whether it was paid or voided before you rely on it.