Involuntary Churn and the Subscription Grace Period in an API Product
A failed card should not take down a customer's production app. These are the design lessons behind the subscription grace period we built at SignatureAPI to handle involuntary churn in a developer API.
A card fails. The billing system retries it a few times. Then it cancels the subscription. In an API product, that last step can switch off a customer’s production app. And maybe nobody on their team knew an invoice was open.
That is the problem behind involuntary churn. Involuntary churn is when you lose a customer because a payment failed, not because they decided to leave. They still want the product. Their card expired, or the invoice went to an inbox nobody reads. The usual answer is a subscription grace period. A grace period is a window of time after a failed payment where the account keeps working while you try to reach the customer.
In October 2026 we changed how SignatureAPI handles unpaid accounts. I wrote about what we shipped on the SignatureAPI blog. This post is about the reasoning behind it. I cover why the common pattern hurts developer products, what each stage of our process is for, and which trade-offs we accepted.
Who reads billing emails
Start with a simple question. When a payment fails, who finds out?
At SignatureAPI, most customers reach us through code. A team writes the integration once, ships it, and moves on. From then on, their backend creates envelopes on its own. An envelope is a package of documents sent out for signature. Nobody needs to log in. The dashboard sits unopened.
Billing goes somewhere else. Invoices and payment notices go to the email address on the account. Often that is a founder or a shared finance inbox. The engineers who run the integration may never see them. And we can only know that an email was sent. We cannot know that a person read it.
So there are two groups of people. One group gets the warnings. The other group owns the system that breaks. In many accounts they never talk about billing.
When we looked, the result of this gap was real. Some accounts had failed payments from months before and were still sending documents. Nothing had told them, in a way they noticed, that something was wrong.
Why retries are not enough
The standard pattern in SaaS is retry, then cancel. Retry the card a few times. When the retries run out, end the subscription.
It is popular for good reasons. It is easy to build and easy to explain. For an app people open every day, it mostly works. The person who loses access is the same person who uses the app, so they notice at once and fix the card.
An API product breaks that link. The person who notices is not a user of the dashboard. It is an engineer looking at failed requests. Or worse, it is one of their own customers, who sees an error inside an app that has nothing to do with us.
The key point is simple. Running out of retries is a fact about the payment. It says nothing about whether a human on the customer side is aware. Cancelling at that moment treats “the card failed” as if it meant “the customer was warned”. In a developer product, those are often two very different things.
The shortcut we rejected
Our second idea looked clever at first. Move unpaid accounts back to the free trial plan, and add a button to reactivate. Trial accounts already have no live access, so we could reuse a state the product already had.
It did not survive a closer look. A trial account and an unpaid account seem alike from outside. Inside the product, they mean opposite things. A trial account is a new customer who has never paid. An unpaid account is an existing customer who owes money and has a full history with us.
Signup, checkout and activation are all designed for the new customer. To reuse the trial state, each of those flows would need special cases. They would have to know that this “trial” account is really an old customer with an open invoice. Those special cases would sit in code that has nothing to do with collecting payments. Every future change to onboarding would have to remember them.
The lesson is about meaning. Reusing a state saves time only when the meaning is the same. When the meaning is different, the saved work comes back later as exceptions spread across the product. We gave unpaid accounts their own state instead.
Four stages, one exit
The design we shipped in October 2026 has four stages:
- A grace period, where nothing changes.
- A pause of live mode only.
- A one-time resume that the customer can start on their own.
- Cancellation, only after all of the above.
At every stage there is one exit. Pay the invoice, and live access comes back right away. There is no separate reactivation step to find. This rule keeps the whole process easy to explain. At any stage, the answer is the same action.
Designing the grace period
When a payment fails, the account keeps working for 21 days. Live mode, test mode and the dashboard all behave as normal. During those days, the address on the account gets a series of emails. The first goes out on day 0. Then one each week. Then a final reminder 7 days before the pause and another 1 day before.
The design choices are in the content of each email, more than in the schedule.
First, each email stands alone. Every message says the amount due, the date live access will pause, and what will keep working after that. We assumed the reader may have missed every earlier email. So no email depends on another one to make sense.
Second, the date goes in the subject. The final reminders put the pause date in the subject line. Someone scanning a busy inbox sees it without opening anything.
Third, people can reply. Any of these emails can be answered to ask for more time. A grace period with fixed rules can still bend for a real person with a real reason.
A good grace period is not only a delay. It is a delay plus a clear message that says what happens, when, and what to do.
Pause only live mode
On day 21, live access pauses. This is the stage where the main trade-off lives. We want someone’s attention. We do not want to break things that are already running.
So the pause is narrow on purpose.
- Requests with live API keys get an error. It says live access is paused because of an unpaid invoice, and it links to a docs page with the steps to fix it.
- Test mode keeps working, so the team can keep building and testing.
- The dashboard keeps working.
- Envelopes already in progress still complete. A signer in the middle of signing is not affected.
The error message deserves its own note. We wrote it for an engineer who has never heard of the invoice. That person will probably meet it first, in a log or an alert. It has to explain itself without any of the emails.
The general idea works for any API product. When you must stop something, think about who will see the failure first. Write the message for that person, not for the person you emailed.
At the same time, everyone on the account sees a “Live access paused” banner in the dashboard. It has three actions: Pay now, Resume for 5 days, and Go to billing. One more email also goes to the account address.
The one-time resume
The resume solves a specific gap. The person who sees the pause first is often not the person who can pay. And the person who can pay may need a few days.
Without the resume, that team would be stuck. Production would stay down until finance acted, or until they reached our team.
“Resume for 5 days” gives live access back for five days. Two limits make it safe:
- It works once per unpaid period. It buys time to pay. It cannot push payment away forever.
- Only users with billing permission see the button. Other members see the same banner with a note to contact the account owner.
While the resume runs, the banner counts down the days left. That way nobody is surprised when the five days end.
In short, the resume turns “contact support and wait” into one click. It works only once, and only for someone allowed to make billing decisions.
When cancellation is right
About a week after the pause, if the invoice is still open, the account is cancelled. We never cancel while a resume is running.
A cancelled account goes back to the free trial plan. Its live keys stop working. It can subscribe again at any time.
This may look like the trial idea we rejected earlier. The difference is timing. Earlier, the trial state would have been a stage inside the unpaid period, with an open subscription and money owed. Here, cancellation ends the unpaid period. After it, there is no subscription. Coming back means subscribing again, which is exactly what the trial flows are built for. The same state is wrong in one place and right in another, because the meaning matches only at the end.
What we still don’t know
I want to be honest about the limits of this design. The first accounts reach their pause date at the end of October. So everything after day 21 had not run for real customers when we published.
We don’t yet know how many accounts will use the resume. We don’t know if five days is the right length. Our plan is to watch how the first accounts move through the stages. We will also read the replies asking for more time. Only then will we change anything.
That is the last design choice. A process for failed payments touches money and production systems at the same time. We chose to ship a careful version, watch it, and adjust, instead of guessing perfect numbers up front.
If you build subscriptions for a developer product, start with one question. Who finds out when a payment fails? The full description of what SignatureAPI shipped, with the email schedule and screenshots, is in How we handle unpaid accounts without breaking production.