> ## Documentation Index
> Fetch the complete documentation index at: https://help.gostanna.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Integration

> Sync subscription revenue and payment health from your Stripe account

## 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

<CardGroup cols={2}>
  <Card title="Subscription Tracking" icon="credit-card">
    Automatic synchronization of active subscriptions with revenue data
  </Card>

  <Card title="MRR Calculation" icon="dollar-sign">
    Exact Monthly Recurring Revenue per client, updated automatically
  </Card>

  <Card title="Subscription Events" icon="bell">
    Track upgrades, downgrades, cancellations, and payment failures
  </Card>

  <Card title="Payment Health" icon="heart-pulse">
    Monitor payment status and billing issues to prevent churn
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Initiate OAuth Flow">
    Navigate to `/api/integrations/stripe/start` or click "Connect Stripe" in integrations
  </Step>

  <Step title="Authorize Access">
    Sign in to Stripe and grant Stanna permission to access:

    * Customer data
    * Subscription information
    * Payment and invoice data
    * Product catalog (read-only)
  </Step>

  <Step title="Verify Connection">
    Check status at `/api/integrations/stripe/status` to confirm:

    * Active connection status
    * Last successful sync time
    * Account information
  </Step>

  <Step title="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
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion title="Integration shows as disconnected">
    **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
  </Accordion>

  <Accordion title="MRR data not appearing or incorrect">
    **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
  </Accordion>

  <Accordion title="Customers not mapping to clients">
    **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
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Clean Customer Data" icon="sparkles">
    Maintain accurate customer emails and metadata in Stripe for proper mapping
  </Card>

  <Card title="Consistent Pricing" icon="table">
    Use clear subscription naming and consistent billing intervals
  </Card>

  <Card title="Monitor Sync Status" icon="eye">
    Check integration status regularly to catch connection issues early
  </Card>

  <Card title="Payment Method Updates" icon="credit-card">
    Proactively reach out when payment methods are expiring or failing
  </Card>
</CardGroup>

## 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

<Warning>
  **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.
</Warning>

<Info>
  **Need help with Stripe setup?** Contact [support@gostanna.com](mailto:support@gostanna.com) for assistance with connection or data mapping issues.
</Info>