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.

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.

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.

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