Stripe's Billing Portal Can Now Deep-Link to 'Update Your Details.' Most Dunning Emails Only Link to 'Update Your Card.'

On August 26, 2026, Stripe added a new value to the billing portal's flow_data.type parameter: customer_update. It's a small, easy-to-miss line in a changelog dominated that same day by a much louder release — the Billing.FeedbackOption API we covered in our look at Stripe's custom cancellation reasons. But this one touches a different part of the churn stack entirely, and it's worth pulling apart on its own, because it exposes a gap most dunning setups have been quietly living with for years: they only know how to send a customer to fix their card.

What actually shipped on August 26

Stripe's own changelog entry is direct about it: setting flow_data.type to customer_update "creates a deep link that navigates your customer directly to the billing information page in the customer portal, where they can update their details." That's it — no new object, no new webhook events, just a new destination you can point a portal session at. It's additive: Stripe is explicit that "no changes are required for existing integrations," so nothing breaks if you never touch it.

What makes it worth a second look is what "billing information" actually means here, because it's a different page from the one most SaaS dunning flows already link to. The portal's customer_update flow lets a customer edit their name, email, billing address, and tax ID. It does not touch their card. For that, the portal has had a separate flow for years: payment_method_update. Stripe now has five distinct portal deep links, and each one exists because it maps to a genuinely different action a customer needs to take.

Why "update your card" was never the whole fix

Our own guide to Stripe dunning makes the case that every recovery email should link straight to the customer portal rather than making someone hunt for a settings page — friction in the update flow is a silent recovery killer. That advice still holds. What it assumed, reasonably at the time, is that the update a failing customer needs is almost always a card update. For a meaningful slice of failures, it isn't.

Stripe's own decline-code taxonomy separates these cleanly, and we went deep on how that taxonomy now travels consistently across payment methods in our piece on Stripe's unified decline vocabulary. Two codes in particular describe a completely different failure mode than a bad card: incorrect_address, where "the address entered by the customer is incorrect," and incorrect_zip, where "the postal code is incorrect." Neither of those is fixed by adding a new card. They're fixed by editing the billing address already on file — which, until August 26, had no dedicated deep link at all. A dunning email that only offered payment_method_update was, for this category of failure, sending the customer to fix the one thing that wasn't actually broken.

The scale of that mismatch is bigger than most teams assume, because AVS-driven declines get mentally filed under "card problem" by default. AVS checks the billing address a customer supplies against what their card issuer has on file, and issuers vary widely in how strictly they enforce a match — a customer who moved eight months ago and never updated a SaaS subscription's billing address is a completely ordinary, completely non-fraudulent way to trip this check.

Riskified's own numbers put this starkly: even orders with zero address match at all were, seven times out of ten, real purchases from real customers — not fraud, just outdated or mistyped billing data. Most merchants don't run Riskified-grade override logic on top of a raw AVS check, which means the default behavior on a mismatch is often a flat decline, full stop. That decline lands on your invoice as incorrect_address or incorrect_zip, gets treated by your dunning stack as a generic failed payment, and gets the same "update your card" email as an expired Visa — which does nothing, because the card was never the problem.

The B2B version of the same gap: tax ID, not address

For subscription businesses selling to companies rather than individuals, the equivalent failure rarely shows up as a card decline at all — it shows up as an invoice that never gets paid because it never gets approved. A tax ID that's expired, was entered with a typo, or belongs to a subsidiary that's since been restructured is a routine reason an accounts payable team kicks an invoice back before anyone even reaches a payment step. That failure mode sits closer to what we've written about in net terms and invoice-based B2B billing: the payment itself was never attempted, so none of your card-decline dunning logic ever fires, and the account just quietly stalls in accounts payable until someone notices the renewal never landed.

customer_update is the same fix for both failure modes, because both are billing-information problems rather than payment-method problems. A dunning or renewal-reminder workflow that can tell the difference between "your card needs updating" and "your billing details need updating" can now send the right link for each, instead of relying on the customer to somehow find the correct page inside a portal home screen they were never deep-linked into.

Wiring it into an actual dunning flow

The integration is a few lines, not a rebuild. On your invoice.payment_failed webhook, read the charge's decline_code before you generate the portal link for your recovery email:

• Card-level codes — expired_card, insufficient_funds, incorrect_cvc, invalid_number — create a portal session with flow_data[type]=payment_method_update.
• Billing-detail codes — incorrect_address, incorrect_zip — create a portal session with flow_data[type]=customer_update instead.
• No charge attempt at all (a stalled B2B invoice) — send customer_update proactively as part of your renewal-reminder sequence, before the invoice due date, rather than waiting for a decline that will never come.

Every dunning email you send already carries the decline reason in the webhook payload that triggered it. The only change is a branch in that logic instead of a single hardcoded flow type — the kind of fix that takes an afternoon, not a sprint.

None of this replaces the harder problem of a subscriber who's decided, for real product or price reasons, that they're done. That's the moment CancelFlow is built for, and it's a different conversation than a stale ZIP code. But involuntary churn from a wrong billing address or an expired tax ID is pure waste — a customer who never intended to leave, lost to a form field nobody prompted them to fix. Run your current dunning recovery rate through our churn calculator before and after you split this logic out, and the gap between "fixed a card" and "fixed a billing address" is usually the fastest, cheapest win left in an involuntary-churn stack that's already been through a few rounds of optimization.

Frequently asked questions

Stop losing subscribers today

One script tag. One function call. A live cancellation flow in under 10 minutes.