Skip to main content

​
Overview

Connect Stripe to automatically sync subscription revenue and payment status. Track Monthly Recurring Revenue (MRR) per client, monitor subscription events, and get alerted to payment issues before they impact retention.

​
Features

Subscription Tracking

Automatic synchronization of active subscriptions with revenue data

MRR Calculation

Exact Monthly Recurring Revenue per client, updated automatically

Subscription Events

Track upgrades, downgrades, cancellations, and payment failures

Payment Health

Monitor payment status and billing issues to prevent churn

​
Setting Up Stripe Integration

​
Prerequisites

Before connecting Stripe:
  • Stripe account with admin or developer permissions
  • Active subscriptions or recurring revenue in Stripe
  • Understanding of your subscription structure

​
Connection Process

1

Initiate OAuth Flow

Navigate to /api/integrations/stripe/start or click “Connect Stripe” in integrations
2

Authorize Access

Sign in to Stripe and grant Stanna permission to access:
  • Customer data
  • Subscription information
  • Payment and invoice data
  • Product catalog (read-only)
3

Verify Connection

Check status at /api/integrations/stripe/status to confirm:
  • Active connection status
  • Last successful sync time
  • Account information
4

Initial Data Sync

Trigger first sync with POST /api/integrations/stripe/sync:
  • Imports active subscriptions
  • Calculates MRR per customer
  • Maps Stripe customers to client accounts

​
What Data is Synced

​
Active Subscriptions

Stanna syncs all recurring revenue from Stripe:
  • Subscription plans: All active subscription products
  • Billing intervals: Monthly, annual, and custom intervals
  • Customer mapping: Stripe customers linked to client accounts
  • Subscription status: Active, trialing, past due, or canceled

​
Monthly Recurring Revenue (MRR)

Exact MRR calculation per client:
  • Monthly plans: Direct subscription amount
  • Annual plans: Annual amount divided by 12
  • Custom intervals: Normalized to monthly equivalent
  • Multiple subscriptions: Aggregated per customer

​
Subscription Events

Track important subscription lifecycle events:
  • Upgrades: Plan changes that increase revenue
  • Downgrades: Plan changes that decrease revenue
  • Cancellations: Subscription terminations
  • Reactivations: Customers who return after canceling

​
Payment Status

Monitor billing health:
  • Failed payments: Payment method issues or declined charges
  • Past due subscriptions: Billing retry attempts
  • Upcoming renewals: Subscription renewal dates
  • Invoice status: Paid, unpaid, or voided invoices

​
How Stripe Data is Used

Stripe data directly impacts client health and risk assessment:

​
MRR Field Updates

Subscription data automatically updates the MRR field for each client, giving you accurate revenue tracking without manual entry.

​
Health Score Impact

Revenue tier contributes to health score based on your configuration. Higher MRR clients typically get weighted more heavily in your portfolio analysis.

​
Churn Risk Alerts

Payment failures and subscription cancellations trigger churn risk alerts, allowing you to intervene before losing valuable customers.

​
Revenue Analytics

Aggregate MRR data powers revenue dashboards, showing trends, growth, and revenue at risk across your entire customer base.

​
API Endpoints

​
Core Integration

GET  /api/integrations/stripe/start     # Start OAuth flow
GET  /api/integrations/stripe/callback  # OAuth callback handling
GET  /api/integrations/stripe/status    # Check connection status
POST /api/integrations/stripe/sync      # Manual sync trigger
POST /api/integrations/stripe/disconnect # Remove integration

​
Data Management

GET /api/integrations/status            # Overall integration status
GET /api/clients/:id                    # View client MRR data

​
Sync Configuration

​
Sync Frequency

  • Automatic Sync: Every 30 minutes during business hours
  • Manual Sync: Available via API or dashboard
  • Webhook Updates: Real-time updates for critical events (if configured)
  • Background Processing: Large subscription lists processed efficiently

​
Customer Mapping

Stanna maps Stripe customers to clients using:
  • Email matching: Stripe customer email to client stakeholders
  • Domain matching: Stripe customer domain to client records
  • Manual mapping: Override automatic matching if needed
  • Metadata support: Use Stripe metadata for custom mappings

​
Troubleshooting

Common Causes:
  • OAuth token expired or revoked
  • Stripe account permissions changed
  • API key issues (if using legacy integration)
  • Network connectivity problems
Resolution Steps:
  1. Check /api/integrations/stripe/status for specific errors
  2. Re-authenticate at /api/integrations/stripe/start
  3. Verify Stripe account permissions are unchanged
  4. Contact support if issues persist
Troubleshooting Process:
  1. Verify subscriptions are active in Stripe dashboard
  2. Check customer email/domain matches client records
  3. Confirm subscription amounts are properly set
  4. Review currency conversion settings
Data Requirements:
  • Subscriptions must be in “active” or “trialing” status
  • Customers need valid email or domain for matching
  • Subscription prices must be properly configured
  • Multi-currency subscriptions require currency settings
Common Issues:
  • Email addresses don’t match between systems
  • Domain extraction fails from customer email
  • Multiple customers for same client not aggregated
  • New customers not yet synced
Solutions:
  1. Verify customer email matches a client stakeholder
  2. Check domain field in client record matches customer domain
  3. Trigger manual sync to refresh customer data
  4. Use manual mapping in client settings if needed

​
Best Practices

Clean Customer Data

Maintain accurate customer emails and metadata in Stripe for proper mapping

Consistent Pricing

Use clear subscription naming and consistent billing intervals

Monitor Sync Status

Check integration status regularly to catch connection issues early

Payment Method Updates

Proactively reach out when payment methods are expiring or failing

​
Subscription Analytics

​
Revenue Insights

Stripe integration powers key revenue metrics:
  • Total MRR: Sum of all active subscriptions
  • MRR Growth: Month-over-month revenue changes
  • Revenue at Risk: MRR from clients with health issues
  • Churn Rate: Revenue lost to cancellations

​
Customer Segmentation

Segment clients by revenue tier:
  • Enterprise: High-value accounts requiring special attention
  • Growth: Mid-tier accounts with expansion potential
  • Starter: Entry-level accounts for scale operations
  • At Risk: Accounts with payment issues or cancellation signals

​
Subscription Health

Track subscription lifecycle metrics:
  • Active subscriptions: Total count and MRR
  • Trial conversions: Trial-to-paid conversion rates
  • Cancellation trends: Why customers cancel
  • Upgrade/downgrade patterns: Revenue expansion indicators
Data Accuracy: MRR calculations depend on accurate subscription data in Stripe. Ensure subscription prices, billing intervals, and customer information are correct for reliable revenue tracking.
Need help with Stripe setup? Contact support@gostanna.com for assistance with connection or data mapping issues.