Stripe Can Now Tell You Why an Invoice Is Uncollectible. Most Churn Dashboards Still Can't Use That.

Every Stripe-billed SaaS business has the same blind spot in its churn reporting: an invoice with status: "uncollectible" tells you a customer stopped paying, but not why. Did their card get declined four times in a row? Did someone on your support team manually write off a $40 invoice from a customer who complained? Did the subscription get paused on purpose and Stripe correctly decided not to bill it? Until last week, all three looked identical in the API. A changelog entry from September 30 quietly fixes that, and it's worth more attention than it's gotten.

What actually shipped

Stripe added a status_details property to the Invoice object. It's only populated when status is uncollectible, and it carries one meaningful field: status_details.uncollectible.reason. That's an open enum — Stripe can add values later without it being a breaking change — currently covering five cases:

• max_payment_attempts — Smart Retries ran out of attempts without a successful charge. This is the classic failed-payment case.
• payment_not_received — relevant to send_invoice billing, where you're waiting on a bank transfer or manual payment that never arrived.
• subscription_canceled — the subscription behind the invoice was canceled before the invoice could be collected.
• subscription_paused — the subscription had pause_collection set, so Stripe generated the invoice but deliberately didn't attempt to collect on it.
• user_forgiven — someone on your team manually marked the invoice uncollectible, usually through the dashboard.

It's a small-looking addition — one nested string on an object that already had a dozen fields. But it's also the first time Stripe has given you a reliable, first-party way to separate these five situations without stitching together webhooks, dashboard notes, and your own pause_collection state to reconstruct the cause after the fact.

Why "uncollectible" has always been a lie by omission

If you've built involuntary churn reporting on Stripe before, you've probably written something like this: pull every invoice where status = "uncollectible", treat it as a failed payment, and roll it into your churn number. That query has always been wrong for a meaningful slice of the data, and until now there was no clean way to fix it from the API alone.

Consider what actually lands in that bucket today. A customer whose card got declined four times belongs there — that's a real involuntary churn event, and it's what our Stripe dunning guide is built around recovering. But so does an invoice generated behind a subscription you deliberately paused at a customer's request — Stripe still creates the invoice under pause_collection's older mark_uncollectible behavior, and that invoice reports the exact same status as the declined card. So does an invoice a support rep manually forgave because a customer complained about being double-billed. None of those last two are failed payments. All three used to be indistinguishable without reconstructing context Stripe didn't expose.

Two of five reasons are genuine payment failures. Three of five are not churn at all — they're the downstream paper trail of decisions you or the customer already made deliberately. If your dunning dashboard has been counting all five the same way, your involuntary churn rate has been overstated by however much pause and manual-forgiveness volume runs through your account. For a business running a healthy pause offer at scale, that's not a rounding error.

The subscription_paused case is the one worth fixing first

We wrote recently about Stripe's new dedicated pause status for subscriptions, which stops generating invoices entirely while a subscription is paused. If you've migrated to that endpoint, this problem mostly goes away for new pauses — no invoice, nothing to mark uncollectible. But pause_collection hasn't been deprecated, and plenty of cancellation flows — including setups built directly off our own dunning guide — still use it with the mark_uncollectible behavior, which generates the invoice and then marks it uncollectible rather than voiding it outright.

Every one of those invoices was, until this changelog entry, invisible as a distinct category. Now status_details.uncollectible.reason = "subscription_paused" gives you a one-line filter to exclude them from your churn calculation without needing to cross-reference each invoice's subscription against your own pause records.

How to actually use the new field

1. Upgrade your API version deliberately

status_details only appears starting with API version 2026-09-30.endive. Check your current version in Workbench before assuming it's already showing up in your webhook payloads or API responses — if you're pinned to an earlier version, you'll keep getting the old, undifferentiated uncollectible status until you upgrade. Stripe gives you a 72-hour rollback window after upgrading, so there's little reason to delay this one if your webhook consumers are reasonably well-tested.

2. Rebuild your involuntary churn query around the reason field, not the status alone

If your churn dashboard currently does something like WHERE invoice.status = 'uncollectible', change it to filter on status_details.uncollectible.reason IN ('max_payment_attempts', 'payment_not_received'). That single change removes paused and forgiven invoices from your involuntary churn numerator without touching anything else in the calculation. It's the invoice-level equivalent of what we've described before at the subscription level — using cancellation_details.reason instead of a bare canceled status to separate payment-driven cancellations from voluntary ones.

3. Route user_forgiven differently in your support tooling

A user_forgiven invoice is a decision your team made, not a payment outcome. If that volume is showing up anywhere in your churn or recovery reporting, it shouldn't be — it belongs in a support or billing-exceptions report instead, ideally with the agent who forgave it and the reason tagged separately in your own system, since Stripe's field only tells you that it happened, not why.

4. Watch payment_not_received as its own signal if you bill on invoice terms

Businesses running send_invoice billing — net-30 contracts, manual bank transfers — have a fundamentally different recovery motion than card-based Smart Retries. A payment_not_received invoice needs a collections follow-up, not a retry schedule. Lumping it in with max_payment_attempts volume means you're measuring two different operational processes with one number, which makes it hard to tell whether your card dunning or your invoice collections process is the one that needs attention.

What this doesn't fix

The new field tells you why an invoice became uncollectible, not why the underlying payment method failed in the first place. For that level of detail — insufficient funds versus a bank block versus a stolen card — you still need the decline code from the payment attempt itself, which is a separate problem we cover in our guide to decline codes and retry limits. Think of status_details.uncollectible.reason as the top-level sort: it tells you which invoices are real payment failures worth investigating at the decline-code level, and which ones you can stop investigating entirely because they were never failures to begin with.

It also doesn't retroactively tag invoices created before the field existed. If you're rebuilding historical churn numbers, older uncollectible invoices won't have status_details populated — you'll need your existing reconstruction logic (cross-referencing pause records, dashboard audit logs) for anything before late September 2026, and can switch to the native field for everything after.

None of this changes how many customers actually stop paying — it changes whether you can tell the difference between a customer you lost and a customer you chose not to bill. If your cancellation flow already routes customers through pause and discount offers before they fully leave, getting this distinction right matters more over time, not less: the better your pause offer performs, the more subscription_paused invoices accumulate in your Stripe account, and the more your old involuntary churn number was quietly wrong. Running the numbers on what a cleaner split between real failures and deliberate pauses does to your churn rate is a quick exercise with our churn calculator — plug in both the old and new denominators and see how much of your "involuntary churn" was never churn at all.

Frequently asked questions

Stop losing subscribers today

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