How to build Recurly revenue dashboards in Metabase

{
  "mcpServers": {
    "recurly": {
      "command": "npx",
      "args": ["-y", "recurly-mcp"],
      "env": {
        "RECURLY_API_KEY": "YOUR_PRIVATE_API_KEY",
        "RECURLY_REGION": "us"
      }
    }
  }
}

# Install the Metabase CLI
npm install -g @metabase/cli

# Log in (opens your browser; requires Metabase v62+)
mb auth login --url https://your-metabase.example.com

# Load a Recurly CSV export — creates a table AND a model
mb upload csv --file recurly-subscriptions.csv --collection root

# Refresh that same table later from a new export
mb upload replace <table-id> --file recurly-subscriptions.csv

Create a polished Metabase dashboard for Recurly revenue analytics.
Work end to end: get the data into Metabase if it isn't there yet, then build.

Goal: Help founders and finance leaders understand recurring revenue, churn,
retention, failed payments, and cohort economics from Recurly data.

Step 1 — Find or load the data:
- First, check what already exists in Metabase (search for Recurly tables and
  models). If durable Recurly data is already present — synced from a warehouse
  or uploaded earlier — use it and skip to Step 2.
- If nothing is there, pull it with the Recurly MCP server using a read-only
  API key: accounts, subscriptions, plans, invoices, and transactions. Write
  each result to a CSV, then load it with the Metabase CLI — run "mb upload csv
  --file <export>.csv" so each upload creates a table and a ready-to-query
  model. Use "mb upload replace <table-id> --file <export>.csv" to refresh an
  existing table instead of creating duplicates.

Step 2 — Inspect before querying:
Do not assume exact table names. Map the available raw tables into these
analytical concepts where possible: Accounts, Subscriptions, Subscription
add-ons, Plans, Invoices, Line items, Transactions, and Coupon redemptions.
Inspect the actual tables and column names first.

Important:
- Build on whatever data is present; don't claim Metabase connects natively to
  Recurly — it reads a database or CLI-uploaded tables.
- Compute MRR from active subscriptions, normalizing every plan to a monthly
  amount (divide annual by 12, etc.). Recurly v3 amounts are already in major
  currency units (decimals), so do not divide by 100 unless your pipeline stored
  minor units.
- Report revenue in a single reporting currency; if multiple currencies exist,
  convert with a documented rate or caveat the mix.
- Separate voluntary churn from involuntary (failed-payment) churn.
- Exclude one-time charges and setup fees from MRR unless explicitly asked.
- Only build a card if its underlying column/metric exists in the data.
- A single CSV is a point-in-time snapshot: MRR movement and cohorts need history,
  so build trend cards only if a warehouse sync or multiple uploads provide it.

Dashboard title: Recurly Revenue Overview

Sections:
1. Executive summary (KPI cards): MRR; ARR; Active subscriptions; Net new MRR this
   month; Gross revenue churn %; Net revenue retention (only if MRR-movement data
   can be derived).
2. MRR movement: New, expansion, contraction, and churned MRR by month.
3. Churn & retention: Customer vs. revenue churn by month; Gross vs. net retention;
   Churn by plan; Trial-to-paid conversion.
4. Failed payments & dunning: Failed transactions and $ at risk; Dunning recovery
   rate; Declines by reason; Past-due subscriptions by age.
5. Cohorts & LTV: Revenue retention by signup-month cohort; Cumulative LTV by
   cohort; ARPU by plan.

Filters: Plan, Billing interval, Currency, Account state, Date range.

Reuse the models Metabase auto-created from uploaded CSVs, or (for a warehouse)
create reusable models: modeled_recurly_accounts, modeled_recurly_subscriptions,
modeled_recurly_invoices, modeled_recurly_transactions, and modeled_recurly_mrr
(a monthly per-subscription MRR model).

Output: Build the dashboard if you have permission; otherwise provide the exact
questions, SQL, model definitions, and layout. Include caveats for any metric that
cannot be calculated from the available data. Reconcile totals against Recurly's
analytics. Keep it practical, dense, and executive-readable. Avoid vanity metrics.

Normalize active subscriptions to a monthly amount and sum.

SELECT
  ROUND(SUM(
    CASE p.interval_unit
      WHEN 'years'  THEN s.unit_amount / 12.0 / NULLIF(p.interval_length, 0)
      WHEN 'months' THEN s.unit_amount / NULLIF(p.interval_length, 0)
    END * s.quantity
  ), 2) AS mrr_now
FROM subscriptions s
JOIN plans p ON p.id = s.plan_id
WHERE s.state IN ('active', 'canceled')  -- canceled but not yet expired still bills
  AND (s.expires_at IS NULL OR s.expires_at > CURRENT_DATE);

Expirations against subscriptions active at each month's start.

WITH months AS (
  SELECT generate_series(
    date_trunc('month', CURRENT_DATE - INTERVAL '11 months'),
    date_trunc('month', CURRENT_DATE),
    INTERVAL '1 month'
  ) AS month
)
SELECT
  m.month,
  COUNT(*) FILTER (
    WHERE date_trunc('month', s.expires_at) = m.month
  ) AS churned_subscriptions,
  COUNT(*) FILTER (
    WHERE s.activated_at <= m.month
      AND (s.expires_at IS NULL OR s.expires_at > m.month)
  ) AS active_at_month_start
FROM months m
CROSS JOIN subscriptions s
GROUP BY m.month
ORDER BY m.month;

Declined transactions by week and reason — the dunning worklist.

SELECT
  date_trunc('week', t.created_at) AS week,
  COUNT(*)                          AS failed_transactions,
  ROUND(SUM(t.amount), 2)           AS dollars_at_risk,
  t.status_message
FROM transactions t
WHERE t.status = 'declined'
  AND t.created_at >= CURRENT_DATE - INTERVAL '90 days'
GROUP BY 1, t.status_message
ORDER BY 1, dollars_at_risk DESC;