Version 0.7.3

FreezeSub Documentation

Everything you need to know to get FreezeSub running and saving subscribers.

Quick Start

Get from zero to saving subscribers in under 5 minutes:

  1. 1

    Install FreezeSub from the Stripe App Marketplace and authorize the required permissions

  2. 2

    Open FreezeSub in your Stripe Dashboard → Apps → Settings. Enable the pause page, configure durations and branding, then click "Save settings"

  3. 3

    Click "Disable cancel in portal" to prevent subscribers from cancelling directly in the Stripe Customer Portal

  4. 4

    Copy your Cancel Page URL (https://freezesub.com/cancel/your_account_id)

  5. 5

    Paste it wherever subscribers would normally cancel — as your cancel button, in emails, or in help docs

Installation

Prerequisites

  • An active Stripe account (any plan)
  • At least one active subscription product in Stripe
  • A place to share your Cancel Page URL with subscribers (cancel button, email, help docs)

Stripe App Marketplace Install

FreezeSub is distributed exclusively through the Stripe App Marketplace. This means no npm package, no webhook endpoints to configure, and no API keys to manage.

From Stripe Dashboard:

  1. Click the Apps icon in the left sidebar
  2. Click Explore apps or go to FreezeSub on Stripe Marketplace
  3. Search for FreezeSub
  4. Click Install app
  5. Review and accept the required permissions
  6. You'll be redirected back to your Stripe Dashboard with FreezeSub active

Required Permissions

FreezeSub requests only the permissions it needs:

PermissionWhy
Read subscriptionsTo check subscription status and eligibility for pausing
Write subscriptionsTo pause and resume subscriptions via pause_collection
Read customersTo look up subscribers by email on the cancel page
Write secret storeTo securely store the per-merchant signing secret
Write billing portalTo disable the cancel button in the Customer Portal

Configuration

Initial Setup

After installing, open FreezeSub in your Stripe Dashboard (Apps → FreezeSub → Settings) and complete these steps:

  1. Check "Enable pause page" to activate the subscriber-facing pause flow
  2. Click "Disable cancel in portal" — this removes the cancel button from Stripe's Customer Portal so subscribers go through your FreezeSub cancel page instead
  3. Copy your Cancel Page URL and paste it as your cancel button destination in your app, emails, or help docs
  4. Click "Save settings"

Pause Durations

First pick a unit — weeks or months — then tick which lengths to expose. All three options within the chosen unit can be enabled; at least one must be selected.

Monthly pauses (the default — best for SaaS and most recurring services):

  • 1 month — Good for seasonal businesses or subscribers who need a short break
  • 2 months — Most commonly selected option
  • 3 months — Best for longer-term pause scenarios

Weekly pauses (for content, coaching, or short-cycle products):

  • 1 week — A brief breather, e.g. while travelling
  • 2 weeks — Common for short breaks without losing momentum
  • 3 weeks — Longest weekly option before rolling to monthly

Billing is identical regardless of unit: $5 per save, capped at $99/month. A pause is a pause — you pay for the prevented cancellation, not the length.

Pause Page Customization

The pause page is the customer-facing offer. Customize:

  • Headline — e.g., "Need a break? Pause instead."
  • Description — explain what a pause means for them
  • Brand color — your primary brand hex color
  • Logo URL — displayed at the top of the pause page

Cancel Page URL vs Pause Page URL

FreezeSub provides two types of URLs:

Cancel Page URL (recommended)

https://freezesub.com/cancel/your_account_id

One link for all subscribers. They enter their email, find their subscription, and see the pause offer. No subscription ID needed.

Pause Page URL (direct link)

https://freezesub.com/pause/your_account_id?sub=sub_xxx

Links directly to the pause offer for a specific subscription. Requires appending the subscription ID.

Tip: Use the Cancel Page URL as your default cancel destination — it works for all subscribers without needing a subscription ID.

How the Cancel → Pause Flow Works

1
Subscriber clicks your cancel link

When a subscriber clicks your cancel button (which points to your FreezeSub Cancel Page URL), they land on the cancel page.

2
Email lookup

The subscriber enters their email address. FreezeSub looks up their Stripe customer record.

3
Email verification (OTP)

A 6-digit verification code is sent to the subscriber's email. They enter the code to prove they own the email address. This prevents unauthorized access to subscription management.

4
Subscriber selects their subscription

After verification, the subscriber sees their active subscription(s) and clicks the one they want to manage.

5
Pause offer with reasons

The subscriber sees your branded pause page with cancellation reasons (too expensive, not using it, switching, temporary, other). They choose a pause duration (1–3 weeks or 1–3 months, depending on what the merchant enabled) and confirm to pause.

6
Or cancel anyway

If they click "No thanks, I still want to cancel", they see an "Are you sure?" confirmation. Clicking "Yes, cancel" cancels the subscription at period end.

7
Subscription paused or cancelled in Stripe

If they pause, FreezeSub calls Stripe's pause_collection API — no invoices during the pause. If they cancel, the subscription is set to cancel at period end.

8
Auto-resume

When the pause period ends, Stripe automatically resumes billing. No manual intervention needed.

Note: Subscribers always have the option to cancel. The pause page includes a "No thanks, I still want to cancel" link. After clicking it, they see an "Are you sure?" confirmation before the subscription is cancelled at period end. FreezeSub offers a pause — it never prevents cancellation.

Analytics

FreezeSub's analytics are visible directly in your Stripe Dashboard (Dashboard Home → FreezeSub panel). You can see:

  • Total saves — pauses accepted instead of cancellations
  • Revenue retained — estimated MRR saved based on subscription amounts
  • Active pauses — current subscribers in pause state
  • Successful resumes — subscribers who completed the full pause and resumed billing
  • Why subscribers pause — breakdown by reason (too expensive, not using, switching, temporary, other)
  • Daily breakdown — pauses and resumes per day over the last 30 days

Pricing

FREE
$0

Up to 10 saves/month, always free.

  • ✓ 10 pauses/month
  • ✓ Basic analytics
  • ✓ Standard pause page
PRO
$5 / save

Capped at $99/month. Unlimited after cap.

  • ✓ Unlimited pauses
  • ✓ Full analytics
  • ✓ Branded pause page
  • ✓ Priority support

FAQ

How do subscribers reach the pause page?

You share your Cancel Page URL (https://freezesub.com/cancel/your_account_id) wherever subscribers would normally cancel — your app's cancel button, emails, help docs. When they click it, they enter their email, find their subscription, and see the pause offer.

Does FreezeSub work with annual subscriptions?

Yes. FreezeSub works with monthly and annual Stripe subscriptions. For annual plans, the pause pauses billing collection for the specified period.

Can subscribers still cancel if they don't want to pause?

Absolutely. The pause page always includes a "No thanks, cancel my subscription" option at the bottom. FreezeSub never prevents a subscriber from cancelling if that's what they truly want.

What happens to the subscription during a pause?

Stripe's pause_collection feature is used, which stops billing. The subscription remains active in Stripe but invoices are not generated. The subscriber retains access to the service during the pause period — this is up to the merchant to enforce based on their product.

What if a subscriber cancels during the pause period?

The subscriber can still cancel during the pause. If they do, FreezeSub detects the cancellation event and cleans up the pause record.

Is there a limit to how many times a subscriber can pause?

By default, one active pause per subscriber. You can configure this in the Settings panel. Most merchants allow one pause per 12-month period.

What does FreezeSub count as a "save"?

A save is counted when a subscriber accepts a pause offer. This is the billable event. A save that later results in cancellation during the pause period is still counted as a save (the pause was provided).

Why should I disable cancel in the Customer Portal?

If cancel is still enabled in Stripe's Customer Portal, subscribers can bypass the FreezeSub flow entirely. Disabling it ensures all cancellation attempts go through your Cancel Page URL, where they see the pause offer first.

Security

FreezeSub is built with security as a core principle. Here's what we do to protect your data:

✓
Per-merchant signing secrets — Each merchant gets a unique 256-bit signing secret. No shared secrets between merchants.
✓
HMAC-SHA256 authentication — All authenticated API requests use HMAC-SHA256 with timing-safe comparison to prevent timing attacks.
✓
Timestamp freshness check — Requests older than 5 minutes are rejected to prevent replay attacks.
✓
Signed pause page URLs — Pause page links are cryptographically signed and expire after 30 minutes. Tokens are bound to specific merchant + subscription + customer.
✓
Email verification (OTP) — Subscribers must verify their email with a 6-digit one-time code before viewing or managing subscriptions. This prevents unauthorized subscription manipulation.
✓
Rate limiting — All endpoints are rate-limited per IP. Bootstrap auth has additional stricter limits.
✓
Input validation — All inputs are validated with Zod schemas. Stripe IDs must match format (acct_xxx, sub_xxx, cus_xxx).
✓
CORS protection — API only accepts cross-origin requests from Stripe Dashboard domains.
✓
No payment data stored — FreezeSub never stores credit card numbers, bank accounts, or payment method details.
✓
Minimal data retention — We store only what's needed: merchant settings, pause records, and aggregated stats.
✓
Error message sanitization — Production errors never expose database schema, environment variables, or stack traces.

For Stripe Reviewers

Step-by-step instructions to test the complete FreezeSub flow end-to-end.

Prerequisites

  • A Stripe test-mode account with at least one active test subscription
  • The test subscription must have a customer with a valid email address

Setup (one-time)

  1. Install FreezeSub from the Stripe App Marketplace (or sideload for review)
  2. Open your Stripe Dashboard → click the FreezeSub app → go to Settings
  3. Check "Enable pause page"
  4. Click "Save settings"
  5. Click "Disable cancel in portal (recommended)" — this removes the cancel button from the Stripe Customer Portal
  6. Note the Cancel Page URL shown in Settings — it looks like: https://freezesub.com/cancel/acct_xxx

Testing the subscriber flow

  1. Open the Cancel Page URL in your browser (or an incognito window)
  2. You'll see a page asking for the subscriber's email address
  3. Enter the email address of a test customer who has an active subscription
  4. Click "Find my subscription"
  5. A 6-digit verification code will be sent to that email — enter the code to verify
  6. After verification, the page will show the customer's active subscription(s) — click the one to cancel
  7. You'll be redirected to the branded FreezeSub pause page
  8. Select a reason for cancelling (e.g., "Too expensive")
  9. Choose a pause duration (e.g., "2 months")
  10. Click "Pause my subscription"
  11. You'll see a success confirmation — the subscription is now paused

Verification

  1. Go to your Stripe Dashboard → Subscriptions → open the test subscription
  2. Verify the subscription status shows as paused (pause_collection is set)
  3. Go to Dashboard Home → the FreezeSub panel should show the save in analytics
  4. The subscription will auto-resume at the end of the pause period (Stripe native behavior)

Testing the "cancel anyway" path

  1. Follow steps 1–7 above to reach the pause offer page
  2. Instead of pausing, click "No thanks, I still want to cancel" at the bottom
  3. You'll see an "Are you sure?" confirmation page
  4. Click "Yes, cancel" to confirm
  5. Verify in Stripe Dashboard: the subscription should show cancel_at_period_end: true

Key behaviors to verify

  • Email verification: a 6-digit OTP is sent and must be entered before subscriptions are shown
  • The cancel page correctly looks up customers by email via Stripe API
  • Only active subscriptions are shown (not already-cancelled or paused ones)
  • The pause page displays the merchant's configured brand color and headline
  • After pausing, the subscription's pause_collection is set in Stripe
  • Analytics in the FreezeSub Dashboard panel reflect the new save
  • The Customer Portal no longer shows a cancel button (if "Disable cancel in portal" was clicked)

Support

Need help? We're here.

Email support: hello@freezesub.com

Response time: Free tier — 2 business days. Pro — 24 hours.

When contacting support, please include your Stripe Account ID and a description of the issue.