Documentation

Everything you need to set up, configure, and get the most out of ChurnShield. Recover failed Stripe subscription payments with smart retries, dunning emails, and real-time analytics.

Quick Start Guide

Get up and running with ChurnShield in under 2 minutes. No code changes required.

What Happens After You Connect

Once your Stripe account is connected, ChurnShield does the following automatically:

• Webhook registration -- ChurnShield registers a webhook endpoint with your Stripe account to listen for invoice.payment_failed and related events.
• Decline classification -- Each failed payment is categorized as a soft decline (temporary, retryable), hard decline (card invalid, dunning only), or fraud-related (blocked).
• Automatic recovery -- Soft declines are queued for smart retries. Hard declines and exhausted retries trigger the dunning email sequence.
• Dashboard population -- Your recovery dashboard begins tracking failures, retries, recoveries, and revenue metrics in real time.

Understanding Your Dashboard

Your ChurnShield dashboard (/dashboard.html) is the command center for all payment recovery activity. Here is what you will find:

• Metric cards -- At-a-glance stats: total failed amount, total recovered, active failures in progress, and overall recovery rate.
• Recovery trend chart -- A line chart showing recovered revenue over the last 30 days.
• Decline category breakdown -- A donut chart splitting failures into soft, hard, and fraud categories.
• Active failures table -- Every current failure with status, decline code, amount, retry count, and next action.
• Recovery history -- A log of all successfully recovered payments with amounts and dates.
• Event log -- A chronological feed of all webhook events: payment failures, retry attempts, dunning emails sent, and recoveries.

Smart Retry Engine

The Smart Retry Engine is the core of ChurnShield. Instead of retrying failed payments at arbitrary intervals (like Stripe's built-in retry logic), ChurnShield uses an optimized schedule that maximizes recovery rates while avoiding fraud flags.

How It Works

1. A subscription payment fails and Stripe sends a webhook to ChurnShield.
2. ChurnShield classifies the decline code. Only soft declines (temporary issues like insufficient funds, bank timeouts, processing errors) are retried.
3. Retries are scheduled at statistically optimal intervals. The default schedule is 24 hours, then 72 hours, then 144 hours after the initial failure.
4. Each retry calls the Stripe API to re-attempt the invoice payment.
5. If a retry succeeds, the payment is marked as recovered and you are notified.
6. If all retries are exhausted, the failure moves into the dunning sequence.

What Gets Retried

ChurnShield retries soft decline codes including: insufficient_funds, processing_error, generic_decline (when issuer metadata suggests temporary), try_again_later, issuer_not_available, and others. See the FAQ for a full list of retried vs. dunned decline codes.

Custom Schedules

On the Growth plan and above, you can customize the retry schedule from Settings. Set the interval (in hours) for each retry attempt, and choose between 1-5 maximum retries.

Dunning Emails

When a payment cannot be recovered through retries (hard declines, or soft declines that exhaust all retry attempts), ChurnShield sends a 3-email dunning sequence to the customer asking them to update their payment method.

The 3-Email Sequence

1. Email #1: Friendly Reminder -- Sent immediately when dunning begins. A polite, empathetic message letting the customer know their payment failed and providing a link to update their card.
2. Email #2: Urgent Reminder -- Sent 3 days later. Slightly more urgent tone, reminding them their access may be affected if not resolved.
3. Email #3: Final Notice -- Sent 7 days after the first failure. Last chance notification before their subscription may be canceled.

Customization

Enable or disable dunning emails from Settings. On Starter plans and above, the dunning sequence is available.

White-Label Options

On the Growth plan and above, you can white-label all dunning emails with your own company name, logo, and brand color. Customers see your brand, not ChurnShield. Configure this in Settings > White-Label Emails.

SMS Dunning

Available on Growth plans and above. When enabled, ChurnShield sends SMS reminders alongside each dunning email, increasing recovery rates for customers who may miss emails.

How to Enable

1. Go to Settings and find the SMS Dunning section.
2. Toggle Enable SMS Dunning on.
3. SMS is sent via Twilio. Your Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER) must be configured as environment variables in your Netlify dashboard.

What Messages Are Sent

SMS messages mirror the dunning email sequence with concise, action-oriented text. Each message includes a short link to the payment update portal. Messages are only sent to customers who have a phone number on their Stripe profile.

Slack Alerts

Available on Growth plans and above. Get real-time Slack notifications when payments fail, are recovered, or are abandoned.

How to Set Up

1. Create an Incoming Webhook in your Slack workspace.
2. Copy the webhook URL (starts with https://hooks.slack.com/services/...).
3. Go to Settings > Slack Alerts.
4. Toggle Enable Slack Alerts on and paste your webhook URL.
5. Click Send Test Message to verify the connection.

Events That Trigger Alerts

• Payment failed -- A new subscription payment failure is detected.
• Payment recovered -- A previously failed payment is successfully collected.
• Payment abandoned -- All recovery attempts exhausted; the failure is unresolved.

Email Alerts

Available on all plans. Receive email notifications for payment events.

• Payment failure alerts -- Notified when a customer's payment fails.
• Recovery alerts -- Notified when a payment is successfully recovered.
• Abandoned payment alerts -- Notified when all recovery attempts are exhausted.

Configure which alerts you receive and the destination email address from Settings > Alert Notifications. You can also send a test alert to verify delivery.

Recovery Dashboard

The Recovery Dashboard provides a real-time view of your payment recovery performance.

Charts & Metrics

• Total Failed Amount -- Sum of all failed payment amounts in the current period.
• Total Recovered -- Revenue successfully recovered by ChurnShield.
• Active Failures -- Payments currently being retried or in dunning.
• Recovery Rate -- Percentage of failed payments that were recovered.
• Recovery Trend -- Line chart of recovered revenue over time (30-day view).
• Decline Category Breakdown -- Donut chart showing soft vs. hard vs. fraud declines.

CSV Export Reports

Available on all plans. Export your payment data for use in spreadsheets, accounting software, or custom reporting.

Available Report Types

• Failures report -- All payment failures with decline codes, amounts, statuses, and dates.
• Recoveries report -- All recovered payments with amounts and recovery dates.
• Retries report -- Retry attempt history with results.
• Dunning report -- Dunning email send history with open/click status.

How to Download

On the Dashboard, click the Export CSV button in the top-right area. Select the report type you need from the dropdown menu, and the CSV file will download immediately.

Payment Update Portal

When a dunning email is sent to your customer, it includes a secure link to the Payment Update Portal. This is a hosted page where your customer can enter a new credit card or payment method, powered by Stripe Checkout.

• The portal is automatically generated for each failed payment.
• The link is unique and time-limited for security.
• When the customer updates their card, ChurnShield automatically retries the failed invoice with the new payment method.
• On white-label plans, the portal displays your company branding.

Event Log

The Event Log (found at the bottom of the Dashboard) shows a chronological feed of every webhook event processed by ChurnShield.

• payment_failed -- A new payment failure was received from Stripe.
• retry_attempted -- A smart retry was executed (success or fail).
• dunning_sent -- A dunning email was delivered to the customer.
• dunning_scheduled -- A dunning email is queued for future delivery.
• payment_recovered -- A failed payment was successfully collected.

Each event shows the event type, customer email, related amount, and timestamp. Use the event log to audit recovery activity and troubleshoot issues.

Smart Save — Cancel Flow Interception

Smart Save intercepts voluntary cancellations before they happen. When a customer clicks your cancel button, a ChurnShield modal appears with a multi-step flow: reason collection, personalized offer (discount or pause), and outcome tracking. No backend work required on your end.

Widget Setup

Setting up Smart Save takes about 2 minutes:

1. Enable Smart Save in Settings and configure your discount percentage, discount duration, and pause duration.
2. Copy the embed code from the Smart Save section in Settings. It looks like this:

<script src="https://getchurnshield.com/widget.js"
  data-key="cs_live_your_api_key"></script>

3. Paste it before the closing </body> tag in your app.
4. Add the cancel trigger to your cancel button:

onclick="ChurnShield.cancelFlow('cus_xxxxx')"

Replace cus_xxxxx with the Stripe customer ID of the logged-in user. The widget handles everything else — reason collection, offer presentation, and Stripe actions (applying coupons or pausing subscriptions).

How the Cancel Flow Works

1. Step 1 — Reason: Customer selects why they want to cancel (too expensive, not using it, missing feature, switching tools, need a break, or other).
2. Step 2 — Offer: Based on the reason, ChurnShield shows a personalized offer. Price-sensitive reasons get a discount. Usage-related reasons get a pause option.
3. Step 3 — Outcome: If the customer accepts, ChurnShield applies the offer in Stripe automatically. If they decline, the cancellation proceeds and feedback is logged.

Dashboard Stats

The Smart Save section on your Dashboard shows:

• Cancel Attempts — Total number of cancellation attempts intercepted.
• Customers Saved — How many accepted a retention offer and stayed.
• Save Rate — Percentage of attempts that resulted in a save.
• Revenue Saved (est) — Estimated monthly revenue retained from saved customers.
• Cancellation Reasons — Breakdown of why customers tried to cancel, with a visual bar chart.
• Recent Events — Table of individual cancel attempts with customer, reason, offer, and outcome.

AI Smart Offers

AI Smart Offers upgrades Smart Save from static, one-size-fits-all retention deals to personalized offers per customer. When enabled, AI analyzes each canceling customer's context and recommends the optimal offer to maximize save rate.

What AI Considers

• Cancel reason — price-sensitive customers get discounts, usage-related get pauses
• Customer tenure — long-term customers get more generous offers
• Lifetime value — high-LTV customers are worth saving with bigger discounts
• Plan and price — offer is proportional to what they pay
• Additional detail — any text the customer provides is factored in

Offer Types AI Can Recommend

• Discount — custom percentage (10-50%) for a custom duration (1-12 months)
• Pause — subscription pause for 1-3 months
• Downgrade — suggest a lower-tier plan
• Feedback — collect feedback when no offer is appropriate

How to Enable

1. Go to Settings > Smart Save
2. Toggle on AI Smart Offers (below the discount/pause settings)
3. When enabled, AI overrides the static discount/pause settings with personalized offers. Static settings are used as fallback if AI is unavailable.

Win-Back Campaigns

Win-Back Campaigns automatically re-engage customers who have already churned. After a customer's payment is abandoned or they voluntarily cancel, ChurnShield sends a sequence of personalized return offers at 30, 60, and 90 days.

How It Works

1. Daily at 8 PM UTC — ChurnShield scans for newly churned customers (abandoned payments + Smart Save cancellations).
2. 3-email sequence scheduled — Each churned customer gets emails at 30, 60, and 90 days after churn with escalating discounts.
3. Hourly at :30 — Due emails are processed and sent via Resend with your branding.
4. Smart skip — If a customer resubscribes before an email is due, remaining win-back emails are automatically canceled.

Email Sequence

• 30 days — "We miss you!" Warm, nostalgic tone with a return discount (default: 20% off).
• 60 days — "Things have changed." Highlights improvements since they left. Sweeter deal (default: 30% off).
• 90 days — "Last chance." Final urgency with the biggest offer (default: 40% off). Expires in 7 days.

AI Personalization

When AI is enabled, each win-back email is uniquely written based on why the customer left, their previous plan, tenure, and lifetime value. Customers who left for price get discount-focused messaging. Customers who left for a missing feature get product-improvement messaging.

How to Enable

1. Go to Settings > Win-Back Campaigns
2. Toggle on Enable Win-Back Campaigns
3. Optionally enable AI Personalization for unique emails
4. Customize the discount percentages for each stage (30d, 60d, 90d)

AI Recovery Insights

Recovery Insights uses AI to analyze your payment recovery data and generate actionable recommendations. Instead of staring at charts and trying to figure out what to do, AI tells you exactly what's working, what's not, and what to change.

What You Get

• Summary — A 2-3 sentence overview of your recovery performance, referencing actual numbers from your data.
• Highlights — Color-coded pills showing positive trends (green), concerns (red), and neutral observations (gray).
• Recommendations — Prioritized actions ranked by impact (high, medium, low). Each recommendation tells you specifically what to do and why.
• Trends — Whether your recovery rate, failure volume, and key metrics are trending up, down, or stable.

Where Insights Appear

• Dashboard — A dedicated "Recovery Insights" card with a "Refresh" button to regenerate on demand.
• Weekly Digest Email — AI insights are automatically included in your Monday morning digest email alongside the standard stats.

How to Enable

1. Go to Settings > Alert Notifications
2. Toggle on AI Recovery Insights
3. Insights will appear on your next dashboard load and in your next weekly digest

AI Email Personalization

ChurnShield uses AI to write unique, personalized dunning emails for every customer instead of sending the same 3 templates. Each email is tailored based on the customer's history, plan, tenure, and the specific reason their payment failed.

What the AI Considers

• Customer name — personalized greeting
• Decline reason — adapts messaging (never shames for insufficient funds)
• Plan name and price — references the specific subscription
• Customer tenure — acknowledges loyalty for long-term customers
• Lifetime value — emphasizes the value they've received
• Sequence stage — tone escalates from friendly to urgent to final notice

How to Enable

1. Go to Settings
2. Find the AI Email Personalization section
3. Toggle it on
4. Use the Preview buttons to see sample AI-generated emails with your branding

Fallback Behavior

If the AI is temporarily unavailable, ChurnShield automatically falls back to the standard email templates. No emails are ever lost or delayed due to AI availability.

Churn Prediction

ChurnShield scans your Stripe customers daily to detect cards that are about to expire. When an expiring card is found, the customer receives an automated email prompting them to update their payment method — before the next charge fails.

How It Works

• Runs automatically every day at 8:00 AM UTC.
• Checks all active customers for cards expiring within the next 30 days.
• Sends a branded, friendly email with a direct link to update their card.
• Tracks predictions in your dashboard so you can see which customers were notified.

Enable or disable churn predictions from Settings > Alert Notifications > Churn Predictions.

Webhooks

ChurnShield can send real-time event data to any HTTP endpoint — Zapier, your CRM, a Slack bot, or a custom webhook. Events are delivered as JSON POST requests and signed with HMAC-SHA256 for security.

Event Types

The following events are sent to your webhook URL:

• payment.failed — A new payment failure was detected.
• payment.recovered — A previously failed payment was successfully collected.
• payment.abandoned — All recovery attempts were exhausted without success.
• retry.attempted — A smart retry was executed (includes success/failure status).

Example Payload

{
  "event": "payment.failed",
  "timestamp": "2026-03-30T14:22:00Z",
  "data": {
    "customer_name": "Jane Smith",
    "customer_email": "jane@example.com",
    "amount": 49.00,
    "currency": "usd",
    "decline_code": "insufficient_funds",
    "decline_category": "soft",
    "status": "retrying",
    "stripe_invoice_id": "in_1abc...",
    "stripe_customer_id": "cus_1xyz..."
  }
}

Verifying Signatures

Every webhook request includes an X-ChurnShield-Signature header containing an HMAC-SHA256 signature of the request body. Verify it using your webhook secret (found in Settings):

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return signature === expected;
}

Always verify the signature before processing webhook data to ensure the request came from ChurnShield.

Retry Configuration

Manage smart retry behavior from Settings > Smart Retries.

• Enable / Disable -- Toggle smart retries on or off. When disabled, ChurnShield will still classify declines and send dunning emails, but will not attempt automatic retries.
• Maximum Retries -- Choose between 1 and 5 retry attempts (default: 3). After all retries are exhausted, the failure moves to dunning.
• Retry Schedule -- Set the interval (in hours) for each retry attempt. Defaults are 24h, 72h, and 144h. On Growth plans and above, you can customize these values.

Dunning Configuration

Manage dunning email behavior from Settings > Dunning Emails.

• Enable / Disable -- Toggle the dunning email sequence. When disabled, customers will not receive payment update reminders.
• Email sequence -- The 3-step sequence is sent at fixed intervals: immediately, after 3 days, and after 7 days. The sequence timing is not currently customizable, but each email's tone escalates from friendly to urgent to final notice.

Alert Notifications

Configure email alerts from Settings > Alert Notifications.

• Alert email -- Set the email address where alerts are delivered.
• Payment failure alerts -- Toggle on/off.
• Recovery alerts -- Toggle on/off.
• Abandoned payment alerts -- Toggle on/off.
• Test alert -- Click "Send Test Alert" to verify email delivery.

SMS Settings

Manage SMS dunning from Settings > SMS Dunning. Available on Growth plans and above.

• Enable / Disable -- Toggle SMS reminders alongside the dunning email sequence.
• Twilio credentials -- SMS is powered by Twilio. Set your TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER as environment variables in your Netlify deployment settings.
• Phone number requirement -- SMS is only sent to customers who have a phone number on their Stripe customer profile.

White-Label Email Customization

Available on Growth plans and above. Customize dunning emails so customers see your brand. Configure in Settings > White-Label Emails.

• Company Name -- Displayed in the email header and footer. Defaults to your Stripe account name.
• Logo URL -- A URL to your logo image (PNG or JPG, recommended max width 200px). Displayed at the top of each dunning email.
• Brand Color -- A hex color code used for buttons and accents in the email template. Pick a color that matches your brand identity.

Smart Save Settings

Configure Smart Save from Settings > Smart Save (Growth and Scale plans).

• Enable / Disable — Toggle the cancel flow interception on or off.
• Discount Percentage — The discount offered to price-sensitive customers (default: 30% off).
• Discount Duration — How many months the discount lasts (default: 3 months).
• Pause Duration — How many months a subscription pause lasts (default: 1 month).
• Embed Code — Copy your unique script tag to install the widget in your app.
• Preview — Click "Preview Cancel Flow" to see the modal your customers will experience.

Webhook Settings

Configure webhooks from Settings > Webhook Integration (Growth and Scale plans).

• Enable / Disable — Toggle webhook delivery on or off.
• Webhook URL — The HTTPS endpoint that will receive POST requests (e.g., a Zapier catch hook or your own server).
• Webhook Secret — Auto-generated when you first enable webhooks. Used to verify the X-ChurnShield-Signature HMAC-SHA256 header. Click "Copy" to copy it.
• Test Event — Click "Send Test Event" to send a sample payment.failed event to your webhook URL and verify delivery.

API Key Management

Available on the Scale plan. Generate and manage API keys from Settings > API Access.

• You can create up to 5 API keys per account.
• Keys are prefixed with cs_live_ and are shown only once at creation. Store them securely.
• You can name each key for identification (e.g., "Production Server", "Zapier Integration").
• Revoke compromised keys instantly from the settings page.

API Reference

The ChurnShield Public API lets you integrate recovery data into your own applications, dashboards, and workflows. The API is available on the Scale plan.

Full API documentation with endpoint details, request/response examples, authentication, rate limits, and error handling is available at:

/api-docs.html → View Full API Documentation

Available Endpoints

• GET /status -- Account status, plan, and high-level stats.
• GET /failures -- List payment failures with filtering and pagination.
• GET /recoveries -- List recovered payments.
• GET /analytics -- Aggregate recovery metrics for the last 30 days.
• GET /retries -- List retry attempts and results.
• POST /retry -- Manually trigger a payment retry for a specific failure.

Authentication

All API requests require a Bearer token via the Authorization header. Generate keys from Settings.

Authorization: Bearer cs_live_your_api_key_here

Billing & Plans

ChurnShield offers four plans to fit your subscription volume and feature needs.

Feature	Lite ($29/mo)	Starter ($49/mo)	Growth ($99/mo)	Scale ($199/mo)
Subscriptions	Up to 100	Up to 500	Up to 2,000	Unlimited
Smart Retry Engine	✓	✓	✓	✓
Recovery Dashboard	✓	✓ + Analytics	✓ + Analytics	✓ + Analytics
Email Alerts	✓	✓	✓	✓
CSV Export Reports	✓	✓	✓	✓
3-Email Dunning Sequence	✗	✓	✓	✓
SMS Dunning	✗	✗	✓	✓
Slack Alerts	✗	✗	✓	✓
Custom Retry Schedules	✗	✗	✓	✓
White-Label Emails	✗	✗	✓	✓
AI-Personalized Dunning	✗	✗	✓	✓
AI Recovery Insights	✗	✗	✓	✓
AI Win-Back Campaigns	✗	✗	✓	✓
Smart Save + AI Offers	✗	✗	✓	✓
Churn Prediction	✗	✗	✓	✓
Webhooks	✗	✗	✓	✓
API Access	✗	✗	✗	✓
Priority Support	✗	✗	✗	✓
Custom SLA	✗	✗	✗	✓

Free Trial

The Starter plan includes a 14-day free trial with no credit card required. During the trial, you get full access to all Starter features. At the end of the trial, you can choose to subscribe or your account will be paused.

Upgrading / Downgrading

You can change your plan at any time from your account settings or by contacting support at support@getchurnshield.com.

• Upgrading -- Upgrades take effect immediately. You gain access to new features right away. Your billing is prorated for the remainder of the current billing period.
• Downgrading -- Downgrades take effect at the end of your current billing period. Features exclusive to higher plans will stop working at that time.

Cancellation

All plans are month-to-month with no long-term contracts. You can cancel anytime from your dashboard.

• When you cancel, ChurnShield stops all retries and dunning at the end of your current billing period.
• Your data is retained for 30 days after cancellation in case you want to re-activate.
• There are no cancellation fees or penalties.

Troubleshooting & FAQ