Connect Stripe

Unchurn talks to your Stripe account through Stripe Connect OAuth: one button, sign in to Stripe, and we receive a scoped access token. No API keys to copy, no webhook secrets to paste, and you can revoke us from either side at any time.

Before you connect

A standard Stripe account — the one your customers are already billed on. You don’t need to set up Stripe Connect yourself; Unchurn handles the platform side and your existing account is what gets connected.
Owner or admin role on the Stripe account. Stripe’s OAuth consent screen requires it.
Both test and live of the same Stripe account if you want test-mode demos to work alongside production. They’re separate connections — see Connecting test mode.

The mode toggle in the Unchurn dashboard top bar controls what you view — sessions, metrics, configuration. It does not control which mode the widget runs in. The widget’s mode is decided by the token your server signs (test or live). A merchant viewing test-mode sessions in the dashboard can have live-mode widget traffic running simultaneously, and vice versa. This catches people out; pin it now.

What Unchurn can do on your Stripe account

Stripe Connect grants Unchurn broad access to the account you authorize — Stripe doesn’t offer per-resource scopes through OAuth. Here’s the honest split between what Stripe permits and what Unchurn actually calls in production:

Resource	Stripe permits	What Unchurn actually does
Subscriptions	read + write	Reads on bootstrap; writes only after a customer accepts an offer (apply a pause, discount, plan switch, trial extension, or cancel).
Customers	read + write	Reads only (payment-method and plan signals for eligibility).
Prices and products	read + write	Reads only (for the plan-switch picker).
Coupons	read + write	Creates one coupon per accepted discount; never mutates existing ones.
Invoices and line items	read + write	Reads only (to check whether a subscription has unresolved charges).
Payment intents, charges, payouts	read + write	Never called.
Refunds	read + write	Never called.

Every Stripe call the engine makes is recorded in an audit log tied to the session that triggered it.

What Unchurn will not do

Charge your customers. We never create payment intents or pay invoices.
Issue refunds. Ever.
Create new subscriptions.
Cancel subscriptions outside a session. Every Stripe write is tied to one Unchurn session and recorded for audit.
Touch payouts, balance transfers, or your Stripe payout schedule.
Share data across merchants. Each connected account is isolated.

If you bill one-time invoices, Checkout sessions, or anything that isn’t a Stripe Subscription, those are outside Unchurn’s scope and we don’t touch them.

Connect

Sign up at the Unchurn dashboard with your work email.
After confirming your email, you land on the Connect Stripe screen. The page lists exactly what Unchurn will read and write before you click anything.
Click Connect Stripe. Your browser redirects to Stripe’s hosted OAuth consent page.
Sign in to Stripe (or pick the right account if your login owns several). Stripe shows the scope and the account it will connect.
Click Authorize. Stripe redirects back to Unchurn with a one-time code.
Unchurn exchanges the code for an access token, stores it against your account, and drops you on the onboarding reveal screen with your last 30 days of cancellations.

The whole round-trip is a few browser round-trips with no form filling on your side.

Verify the connection

After the callback completes you should see:

A Connected badge on the Account page next to the connected Stripe account ID.
Your last 30 days of cancellations on the onboarding reveal — Unchurn ran a one-time backfill against your subscriptions to populate the dashboard.
The mode toggle in the top bar matches the mode you just authorized.

If the badge stays gray or the reveal shows zero cancellations on an account you know has them, the connection didn’t complete. The two most common causes:

You authorized the wrong account. The OAuth consent screen offered a list and you picked the sibling account. Disconnect from the Account page and connect again.
Stripe denied the grant. If Stripe shows an “access denied” error during OAuth, you’re not an owner/admin on the account. Ask whoever is to either authorize, or grant you admin first.

Connecting test mode

Test mode is a separate connection. From the dashboard, switch the mode toggle to Test, then click Connect Stripe again. You sign in to Stripe and authorize a test-mode connection on the same Stripe account. The two connections live side by side — neither overwrites the other.

Why connect both? Most teams build their cancel button against test data, validate the flow end to end, and then flip to live. The widget refuses to mix the two: a live-mode token cannot trigger a test-mode session and vice versa.

See Test and live modes for the full picture.

If your connection breaks

A connection can break four ways:

You revoke Unchurn from Stripe’s Connected apps page.
Stripe expires or suspends the OAuth grant (rare; happens on account-level policy changes).
The Stripe account itself is closed or suspended.
You disconnect from Unchurn’s dashboard.

In all four cases the dashboard renders a Reconnect required banner. The widget stops serving offers until reconnected — sessions return an error and the customer sees the Try again later screen. There’s no half-state where some calls succeed.

Reconnect by clicking the banner’s Reconnect Stripe button. The OAuth flow runs again and the new token replaces the broken one. Existing dashboard data — sessions, metrics, configuration — is preserved across reconnects.

Revoke

Two ways, both immediate.

From Unchurn. Account → Stripe connection → Disconnect. Unchurn revokes the OAuth grant against Stripe and clears the stored token.
From Stripe. Settings → Connected apps → remove Unchurn. The next Unchurn request to Stripe returns an auth error and the dashboard shows Reconnect required.

Disconnecting test mode does not affect live mode and vice versa.

Multi-account Stripe organizations

If your Stripe login owns several accounts (e.g. a holdco with multiple brands), the OAuth consent page asks which one to authorize. Pick the account that owns the subscriptions you want Unchurn to manage. To switch the connected account on the same Unchurn workspace, disconnect and connect again — Unchurn binds to whichever account you authorized last.

If you want Unchurn to manage retention on multiple Stripe accounts in parallel, sign up for a separate Unchurn workspace per Stripe account. One workspace = one Stripe connection per mode.

Common pitfalls

Going to production with only test mode connected. The first live-mode cancel-flow open returns a “Stripe not connected” error. Connect live before flipping the mode in your token endpoint.
Revoking mid-flow. If a customer is in the middle of the cancel flow when you revoke, sessions in flight return an error on the next Stripe call and the customer sees the Try again later screen.
Authorizing the wrong Stripe account. Disconnect from the Account page and run Connect Stripe again; Unchurn binds to whichever account you authorized most recently.

Next steps

Quickstart — wire the widget into your app in under ten minutes.
Dashboard — configure cancellation reasons, follow-ups, and the five offers.
Test and live modes — keep test data out of your live analytics.