Cancellations are inevitable. This covers automating the offboarding state machine, why "pending cancellation" is the most important database status, handling the physical door sync, and why hiding the cancel button is a terrible system design choice that leads to chargebacks.

The Reality of Cancellations

Everyone thinks cancellations are a marketing failure. They aren't. They are a predictable system state.

In the old days, gyms forced people to come in person or send a certified letter to cancel. You can't do that anymore. If your web app doesn't have a functional "Cancel Subscription" button, users won't bother calling your front desk. They will just issue a chargeback through their credit card app.

A chargeback costs you a $15 fee and hurts your merchant trust score. A clean cancellation costs nothing.

Handling this digitally looks simple. A user clicks a button, you delete their account. It usually isn't that straightforward. If you actually delete the database row, you ruin your historical reporting and probably break the foreign keys on their past invoices.

Here is how you actually architect a cancellation flow.

Step 1: The "Pending Cancellation" State

When a member hits the cancel button on the 12th of the month, they aren't actually canceled yet. They paid for the whole month. They own access until the 30th.

If you flip their status to canceled right then, your door access system will lock them out immediately. They will be furious.

You need an intermediate state. In Stripe, this is setting cancel_at_period_end = true on the subscription. In your local database, you leave their status as active but display a banner in the UI saying "Access ends on [Date]".

Your system shouldn't do anything else yet. Just wait.

Step 2: Exit Surveys and Friction

The business side will always ask you to put a 10-page survey in front of the cancel button.

Push back on this. If the user is trying to leave, making the UI intentionally broken or tedious just ensures they never come back.

Capture a single reason code. Give them a simple dropdown: "Moving", "Too Expensive", "Injured". Save this to the user record before firing the cancellation API call to your payment gateway.

Sometimes offering a "pause" instead of a cancel works here. From an engineering perspective, a pause is entirely different. It means telling the gateway to skip the next two billing cycles. But it keeps the subscription object alive.

Step 3: Past Due Balances (The Deadlock)

What happens if someone tries to cancel, but their last payment failed? They owe you $50.

This is where things usually go wrong.

A lot of systems block the cancellation UI. "You must pay your balance before canceling." This is logical, but practically, it's a disaster. The user just abandons the app. The gateway keeps trying to charge a dead card for three months, racking up more failed invoices and muddying your financial metrics.

Just let them cancel. Cut your losses. Flag the account internally as bad_debt if you want to prevent them from rejoining later without paying it off. But stop the recurring billing engine from spinning its wheels.

Step 4: The Physical Door Disconnect

So the month ends. The subscription is finally dead.

Your payment gateway will fire a customer.subscription.deleted webhook. This is your actual trigger.

When your worker queue receives this event, now you update your local database status to canceled. And in that same transaction, write an event to your outbox table to revoke their physical credential in the door API.

Do not rely on your own cron jobs to guess when the month is over. Timezones and leap years will mess up your logic. Let the billing gateway dictate the exact second the subscription expires, and just react to the webhook.

Surviving the Offboarding

Building a cancellation flow feels like writing code to lose money.

But a clean offboarding process is actually a retention tool. If a member can cancel in two clicks on their phone when they move away for the summer, they will absolutely rejoin in the fall. If you make them call a manager who only works Tuesdays, they will hate your brand forever.

Keep the state machine simple. Don't process prorated refunds automatically. Rely on the payment provider's timeline, and always assume the final webhook will arrive out of order.