Skip to Content
Configure offersPause

Pause

Pause lets a customer freeze billing for a short window — typically a month or two — and keep the access they already paid for. It’s the right offer when the customer is going through a life event (a wedding, a layoff, a quiet quarter) rather than rejecting your product. Forcing the cancel here loses a future renewal you’d have won back automatically.

Pause is available for monthly subscriptions only. Yearly customers don’t see this tile — see Eligibility for why.

Pick the durations you’ll offer

Each duration you enable becomes a button on the pause screen. Most teams ship 1 and 3 months as the two options. A single shorter pause is enough for life events; a longer one for project-based customers who know they’ll be away.

You can offer up to six months. Going wider than three options usually doesn’t help — three is enough to cover the common cases, and more buttons just slow the decision.

Set the cooldown

After a customer resumes, the widget won’t offer pause again for the cooldown window you set. 90 days is a sensible default. Without a cooldown, a determined customer can pause-resume-pause indefinitely and effectively stop paying.

The cooldown counts from the resume date, not from when the customer accepted. A customer who pauses for three months with a 90-day cooldown can’t pause again for roughly six months total — that’s intentional.

What the customer sees

When they accept, the cancel flow shows a confirmation: paused until a specific date, full access until then, billing resumes automatically.

What happens on Stripe

Unchurn calls subscriptions.update(subscriptionId, { pause_collection: { behavior: 'void', resumes_at: <unix> }}) on the connected account, then reads the subscription back to confirm the field is set. The behavior is locked to 'void', which tells Stripe to immediately void any invoice generated during the pause window. The customer doesn’t owe anything for the time they were paused. The resumes_at is calculated by calendar month in UTC, so a pause that starts on January 31 for one month lands on February 28, not March 2.

The subscription’s status field stays 'active' throughout the pause. This matters for two reasons.

First, Stripe’s customer.subscription.paused event does NOT fire for pause_collection pauses. That event only fires for the separate subscription-level pause API, which Unchurn doesn’t use. Both setting and clearing pause_collection fire customer.subscription.updated instead, with the pause_collection field populated or null.

Second, any access check in your app that reads subscription.status === 'active' will let paused customers keep using the product without paying. See the next section.

Your responsibility: gating product access during pause

Unchurn does not gate product access. The widget records the pause and tells Stripe; what your app does with that signal is up to you. Because subscription.status stays 'active' throughout a pause, an app that checks status alone leaks revenue from the moment the first pause fires.

The safe pattern: subscribe to customer.subscription.updated in your Stripe account and maintain a paused_until column on your own subscription record. When the event payload’s pause_collection is populated, set the column to pause_collection.resumes_at if it’s set, or to a sentinel value meaning “indefinite” if resumes_at is null. When pause_collection itself goes null, clear the column. Then check that column in your access middleware.

This catches every transition that matters: customer pauses via the widget, customer resumes via the widget, the pause window elapses and gets cleared, your team un-pauses someone manually in the Stripe dashboard. All four surface as customer.subscription.updated.

What you do with the column is a product decision. Hard lockout (paywall on every page) feels punitive. Read-only mode (existing data visible, new actions disabled) is the common pattern. Either way, the gating happens in your code, not ours.

When the pause ends

At the resumes_at timestamp, Stripe resumes payment collection on the subscription and the next billing cycle invoices normally. No merchant action required to start billing again.

On Unchurn’s side, an hourly cron reads sessions with elapsed pauses, re-reads the subscription from Stripe, clears pause_collection if it’s still set, and stamps outcome: 'resumed' on the session row so the dashboard reflects the live state. You don’t need to call anything to trigger this.

To react server-side to the resume, listen for customer.subscription.updated and look for pause_collection transitioning from populated to null. The same handler from the previous section covers this case.

Cancelling during a pause

A customer on an Unchurn pause who clicks your cancel button sees a Resume prompt, not the normal cancel flow. The Resume prompt’s primary CTA un-pauses billing on Stripe; the decline link closes the widget and the pause continues.

The persistent Cancel shortcut stays visible on the Resume prompt screen. A customer who has fully decided to leave can still cancel from here. Because pause_collection.behavior is 'void', Stripe lets the cancel-at-period-end schedule complete without first lifting the pause, and the original pause_collection is preserved on the subscription. The customer keeps the paid access they’re entitled to through the period end, then the subscription cancels.

When pause is hidden

The widget hides the pause tile for:

  • Yearly subscriptions (pause is monthly-only).
  • Subscriptions with unresolved or unpaid invoices — Stripe doesn’t void pre-existing invoices during a pause, so pausing partway through a retry leaves the customer with a confusing half-billed state.

Common pitfalls

  • Offering too many durations. Three is plenty; six is too many. Decision-fatigue costs you saves.
  • Cooldown too short. Without a real cooldown, a small set of customers will pause indefinitely.
  • Surprising the customer at resume. Stripe sends a standard billing email when the subscription resumes; that email is your customer’s main signal that billing is active again.

Where to go next

DiscountPlan switch