Track MRR, NRR, churn, and customer concentration from Shopify Partner and Stripe.
Local-first. Your revenue data stays on your machine in SQLite. No third-party analytics service storing your financials.
CLI-driven. No browser, no dashboards to click through. Just run mrrmaid dashboard and get your numbers.
Agent-friendly. Built for automation and AI agents. Structured output, CSV exports, and scriptable commands.
Free. No SaaS fees, no tiers, no "contact sales." MIT licensed, run it forever.
$ mrrmaid dashboard
╭───────────────────────────── Recurring Revenue ──────────────────────────────╮
│ MRR: $75,252.03 | ARR: $903,024.36 │
│ (Shopify: $66,605.18 | Stripe: $8,646.85) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭──────────────────── TTM Revenue (Last 12 Months Actual) ─────────────────────╮
│ $764,922.49 │
╰──────────────────────────────────────────────────────────────────────────────╯
- Multi-source - Combines Shopify Partner + Stripe in one view
- LTV analysis - Customer lifetime value with ARPU and churn-based calculations
- Customer history - Deep-dive into any customer's month-over-month revenue
- Cohort analysis - Track retention by customer vintage
- Concentration risk - Identify over-reliance on top customers
- Resumable sync - Full history backfills that survive interruptions
- Export everything - CSV exports for all data
# With pip
pip install mrrmaid
# Or clone and install locally
git clone https://github.com/ctrlaltdylan/MRRmaid.git
cd MRRmaid
pip install -e .# 1. Configure your API credentials
mrrmaid configure
# 2. Sync your data
mrrmaid sync
# 3. View your dashboard
mrrmaid dashboardmrrmaid configureCreate a .env file:
# Shopify Partner API
SHOPIFY_PARTNER_ACCESS_TOKEN=your_token_here
SHOPIFY_ORGANIZATION_ID=your_org_id
# Stripe API
STRIPE_API_KEY=sk_live_xxxShopify Partner API:
- Go to Shopify Partners → Settings → Partner API clients
- Create a client with "View financials" permission
- Copy the access token and organization ID (from URL:
partners.shopify.com/ORG_ID/...)
Stripe API:
- Go to Stripe Dashboard
- Create a restricted key with these read permissions:
- Customers
- Subscriptions
- Invoices
- Copy the key (
rk_live_...or use a secret keysk_live_...)
Overview of MRR, ARR, LTV, and retention metrics.
$ mrrmaid dashboard
╭───────────────────────────── Recurring Revenue ──────────────────────────────╮
│ MRR: $75,252.03 | ARR: $903,024.36 │
│ (Shopify: $66,605.18 | Stripe: $8,646.85) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭──────────────────── TTM Revenue (Last 12 Months Actual) ─────────────────────╮
│ $764,922.49 │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────── Subscriptions ────────────────────────────────╮
│ Total Subscriptions 476 │
│ Active 471 │
│ Trials 0 │
│ Canceled 0 │
╰──────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────── Retention Metrics ──────────────────────────────╮
│ ARPU $159.77 │
│ LTV $2,056.62 │
│ Churn Rate 7.8% │
│ Net Revenue Retention 109.6% │
│ Gross Revenue Retention 83.7% │
╰──────────────────────────────────────────────────────────────────────────────╯
$ mrrmaid dashboard --source shopify # Filter by sourceMRR breakdown and movement.
$ mrrmaid mrr
╭──────────────────────────── MRR Breakdown ─────────────────────────────╮
│ Shopify MRR $64,384.18 │
│ Stripe MRR $8,409.30 │
│ Total MRR $72,793.48 │
╰────────────────────────────────────────────────────────────────────────╯
MRR Movement
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Component ┃ Amount ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ New MRR │ +$8,234.00 │
│ Expansion MRR │ +$2,891.50 │
│ Contraction MRR │ -$1,205.00 │
│ Churned MRR │ -$3,420.00 │
│ Net New MRR │ +$6,500.50 │
└───────────────────┴────────────────────────────────────────┘
$ mrrmaid mrr --granularity week # Weekly breakdown
$ mrrmaid mrr --start 2025-01-01 # Custom date rangeNet Revenue Retention from existing customers.
$ mrrmaid nrr
╭─────────────────────── Net Revenue Retention (Month) ────────────────────────╮
│ 110.9% │
╰────────────────────────── 2025-01-03 to 2025-02-02 ──────────────────────────╯
Formula Components
Starting MRR (base for calculation)
+ Expansion MRR +$17,091.90
- Contraction MRR -$5,904.86
- Churned MRR -$4,360.58
Gross Revenue Retention 83.6%
Good! Revenue from existing customers is growing.
$ mrrmaid nrr --period quarter # Quarterly NRR
$ mrrmaid nrr --period year # Annual NRRCustomer Lifetime Value analysis.
$ mrrmaid ltv
╭────────────────────── Customer Lifetime Value (Month) ───────────────────────╮
│ $2,056.62 │
╰────────────────────── LTV = ARPU / Monthly Churn Rate ───────────────────────╯
LTV Components
ARPU (Monthly) $159.77
Month Churn Rate 7.77%
LTV (ARPU/Churn) $2,056.62
Lifespan Analysis
Avg Customer Lifespan 12.3 months
LTV (Lifespan-based) $1,957.66
Health Indicators
LTV / ARPU Ratio 12.9x
Active Subscriptions 471
Good! Healthy customer lifetime value.
$ mrrmaid ltv --period quarter # Use quarterly churn rate
$ mrrmaid ltv --period year # Use annual churn rate
$ mrrmaid ltv --source shopify # Filter by sourceCohort-based retention analysis.
$ mrrmaid cohort
╭──────────────────────────────────────────────────────────────────────────────╮
│ Cohort Analysis - Revenue Retention │
│ Shows % retention relative to first month (M0 = 100%) │
╰──────────────────────────────────────────────────────────────────────────────╯
┏━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━┓
┃ Cohort ┃ Cust ┃ Revenue ┃ M0 ┃ M1 ┃ M2 ┃ M3 ┃
┡━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━┩
│ 2025-11 │ 263 │ $159,021 │ 100% │ 124% │ 135% │ 9% │
│ 2025-10 │ 45 │ $12,016 │ 100% │ 102% │ 89% │ 85% │
│ 2025-09 │ 38 │ $8,752 │ 100% │ 95% │ 90% │ 88% │
│ 2025-08 │ 52 │ $15,737 │ 100% │ 89% │ 87% │ 80% │
└──────────┴──────┴──────────┴───────┴───────┴───────┴────────┘
Average M1 Retention: 78.6%
Average M3 Retention: 53.8%
$ mrrmaid cohort --metric customers # Customer count retention
$ mrrmaid cohort --periods 12 # Track 12 months
$ mrrmaid cohort --export cohorts.csv # Export to CSVCustomer concentration and revenue distribution.
$ mrrmaid customers
╭──────────────────────────────────────────────────────────────────────────────╮
│ Customer Revenue Analysis - Month │
│ Total Revenue: $73,289.99 from 357 customers │
╰──────────────────────────────────────────────────────────────────────────────╯
⚠ High concentration risk: Top 10% of customers = 57.8% of revenue
Top 20% = 70.5% of revenue
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━┓
┃ # ┃ Customer ┃ Revenue ┃ % Rev ┃ Cumul % ┃ Txns ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━┩
│ 1 │ acme-store.myshopify.com │ $12,912.19│ 17.6% │ 17.6% │ 8839 │
│ 2 │ widgets-inc.myshopify.com │ $2,858.77│ 3.9% │ 21.5% │ 1142 │
│ 3 │ example-shop.myshopify.com │ $2,260.49│ 3.1% │ 24.6% │ 1493 │
└─────┴────────────────────────────────┴───────────┴───────┴─────────┴──────┘
$ mrrmaid customers --period all # All-time analysis
$ mrrmaid customers --period quarter # Last 90 days
$ mrrmaid customers --cohort 2025-01 # Filter by cohort (first purchase month)
$ mrrmaid customers --limit 50 # Show more customers
$ mrrmaid customers --export cust.csv # Export to CSVDeep-dive into a specific customer's history and LTV.
$ mrrmaid customer "acme-store"
╭────────────────────────────── Customer Details ──────────────────────────────╮
│ acme-store.myshopify.com │
│ Active │
╰──────────────────────────────────────────────────────────────────────────────╯
Lifetime Value $30,446.61
Total Revenue $30,446.61
Monthly ARPU $8,661.63
Transactions 17487
Tenure 3.5 months
First Seen 2025-10-29
Last Seen 2026-02-09
Customer ID gid://partners/Shop/66133852249
Monthly Revenue History
┏━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Month ┃ Revenue ┃ Txns ┃ ┃
┡━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 2025-10 │ $609.00 │ 420 │ █ │
│ 2025-11 │ $2,308.34 │ 1526 │ ████ │
│ 2025-12 │ $8,601.09 │ 2619 │ ████████████████ │
│ 2026-01 │ $13,062.99 │ 8943 │ █████████████████████████ │
│ 2026-02 │ $5,865.19 │ 3979 │ ███████████ │
└─────────┴────────────┴──────┴────────────────────────────────┘
$ mrrmaid customer "cus_abc123" # Stripe customer by ID
$ mrrmaid customer "store" --source shopify # Filter by source
$ mrrmaid customer "acme" --export hist.csv # Export monthly historyChurn rate analysis.
$ mrrmaid churn
╭───────────────────────── Churn Rate (Month) ─────────────────────────╮
│ 5.2% │
╰──────────────────────────────────────────────────────────────────────╯
Churned MRR $3,420.00
Churned Customers 12
$ mrrmaid churn --period quarter # Quarterly churn
$ mrrmaid churn --period year # Annual churnSync data from Shopify Partner and Stripe APIs.
$ mrrmaid sync
⠋ Synced 1200 records...
Sync Results
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Source ┃ Records ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ Shopify Transactions │ 63598 │
│ Stripe Subscriptions │ 174 │
│ Stripe Invoices │ 6389 │
└──────────────────────┴─────────┘
$ mrrmaid sync --days 365 # Last year
$ mrrmaid sync --all # Full history (resumable)
$ mrrmaid sync --all --fresh # Start over from scratch
$ mrrmaid sync --source shopify # Single source onlySyncs are resumable - if interrupted, run again to continue where you left off.
View and export transaction history.
$ mrrmaid transactions
Recent Transactions (20)
┏━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Date ┃ Source ┃ Amount ┃ Customer ┃
┡━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 2025-02-01 │ shopify │ $45.00 │ acme-store.myshopify.com │
│ 2025-02-01 │ stripe │ $299.00 │ cus_abc123 │
│ 2025-01-31 │ shopify │ $12.50 │ widgets-inc.myshopify.com │
└────────────┴─────────┴──────────┴────────────────────────────────┘
$ mrrmaid transactions --limit 100 # Show more
$ mrrmaid transactions --source stripe # Filter by source
$ mrrmaid transactions --start 2025-01-01 --end 2025-01-31
$ mrrmaid transactions --export tx.csv # Export to CSVView active subscriptions.
$ mrrmaid subscriptions
Subscriptions (174 total)
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
┃ ID ┃ Source ┃ Status ┃ MRR ┃ Created ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
│ sub_1abc123... │ stripe │ active │ $299.00 │ 2025-01-15 │
│ sub_2def456... │ stripe │ active │ $99.00 │ 2025-01-10 │
│ sub_3ghi789... │ stripe │ trial │ $0.00 │ 2025-02-01 │
└────────────────────┴────────┴────────┴─────────┴────────────┘
$ mrrmaid subscriptions --status active
$ mrrmaid subscriptions --status canceled
$ mrrmaid subscriptions --export subs.csvSave and view historical metric snapshots.
$ mrrmaid snapshot --save
Snapshot saved for 2025-02-01
$ mrrmaid snapshot
MRR Snapshots
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Date ┃ Total MRR ┃ Active Subs ┃ NRR ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━┩
│ 2025-02-01 │ $72,793.48 │ 308 │ 110.9% │
│ 2025-01-01 │ $68,421.00 │ 295 │ 108.2% │
│ 2024-12-01 │ $65,102.33 │ 280 │ 105.4% │
└────────────┴────────────┴─────────────┴────────┘| Metric | Formula | Good | Warning |
|---|---|---|---|
| ARR | MRR × 12 | - | - |
| TTM Revenue | Sum of last 12 months actual revenue | - | - |
| ARPU | MRR / Active Subscriptions | - | - |
| LTV | ARPU / Monthly Churn Rate | >$1000 | <$500 |
| NRR | (Start + Expansion - Contraction - Churn) / Start | >100% | <90% |
| GRR | (Start - Contraction - Churn) / Start | >90% | <80% |
| Churn | Churned MRR / Starting MRR | <5% | >10% |
| Concentration | Top 10% customer revenue / Total | <30% | >50% |
- App subscription charges
- App usage charges (metered billing)
- One-time app charges
- Service revenue
- Referral commissions
- Subscriptions (with line items)
- Invoices (for historical MRR)
- Metered billing usage
src/mrrmaid/
├── api/
│ ├── shopify.py # Shopify Partner GraphQL client
│ └── stripe_client.py # Stripe REST client
├── models/
│ ├── database.py # SQLite via SQLAlchemy
│ └── transaction.py # Data models
├── services/
│ ├── metrics.py # MRR, NRR, Churn, Cohort calculations
│ └── sync.py # Resumable data sync
├── utils/
│ └── config.py # Configuration management
└── cli.py # Typer CLI
Data is stored locally in mrrmaid.db (SQLite).
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format
black src/
# Lint
ruff src/Contributions welcome! Please open an issue first to discuss what you'd like to change.
MIT
Built for indie hackers who want to understand their revenue without paying for expensive analytics tools.