Analytics & Reporting

const metrics = await recurso.analytics.mrr();

// Response
{
  currency: 'USD',              // the reporting currency
  amount: 4850000,              // normalized total, minor units (alias)
  mrr: 4850000,
  normalized_mrr: 4850000,
  reporting_currency: 'USD',
  breakdown: [
    { currency: 'USD', amount: 3000000, converted_amount: 3000000, rate: 1,       subscriptions: 120 },
    { currency: 'INR', amount: 155000000, converted_amount: 1850000, rate: 0.0119, subscriptions: 214 },
    { currency: 'XTS', amount: 40000, converted_amount: 0, rate: 0, subscriptions: 2,
      error: 'no exchange rate available' }   // excluded from the total, flagged
  ],
  fx: {
    rates: { USD: 1, INR: 0.0119 },
    source: 'live',             // or 'static-fallback'
    as_of: '2026-07-06T10:30:00Z'
  }
}

curl https://api.recurso.dev/v1/analytics/mrr \
  -H "Authorization: Bearer $API_KEY"

const usage = await recurso.analytics.getUsageStats({
  start_date: '2026-06-01',
  end_date: '2026-06-23',
  meter_id: 'meter_api_calls'
});

// Response
{
  data: {
    meter_id: 'meter_api_calls',
    start_date: '2026-06-01',
    end_date: '2026-06-23',
    total_usage: 12450000,
    unique_subscriptions: 342,
    daily_breakdown: [
      { date: '2026-06-01', usage: 540000 },
      { date: '2026-06-02', usage: 610000 },
      // ...
    ],
    top_consumers: [
      { subscription_id: 'sub_acme01', customer_id: 'cust_acme', usage: 2100000 },
      { subscription_id: 'sub_globex', customer_id: 'cust_globex', usage: 1850000 }
    ]
  }
}

curl -G https://api.recurso.dev/v1/analytics/usage \
  -H "Authorization: Bearer $API_KEY" \
  -d start_date=2026-06-01 \
  -d end_date=2026-06-23 \
  -d meter_id=meter_api_calls

const result = await recurso.analytics.ask({
  question: 'Which customers churned last month and what was their MRR?'
});

// Response
{
  answer: "3 customers churned in May 2026 with a combined MRR of ₹45,000. The largest was Acme Corp at ₹28,000/mo.",
  data: [
    { customer_id: 'cust_acme', name: 'Acme Corp', churned_mrr: 2800000, churned_at: '2026-05-12' },
    { customer_id: 'cust_beta', name: 'BetaWorks', churned_mrr: 1000000, churned_at: '2026-05-18' },
    { customer_id: 'cust_nova', name: 'Nova Labs', churned_mrr: 700000, churned_at: '2026-05-25' }
  ],
  query: "SELECT c.id, c.name, s.mrr, s.canceled_at FROM subscriptions s JOIN customers c ON s.customer_id = c.id WHERE s.status = 'canceled' AND s.canceled_at BETWEEN '2026-05-01' AND '2026-05-31'"
}

curl -X POST https://api.recurso.dev/v1/analytics/ask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which customers churned last month and what was their MRR?"
  }'

const overview = await recurso.analytics.getDunningOverview({
  start_date: '2026-06-01',
  end_date: '2026-06-30'
});

// Response
{
  data: {
    total_invoices_in_dunning: 47,
    total_amount_at_risk: 2350000,
    recovered_amount: 1890000,
    recovery_rate: 0.804,  // 80.4%
    currency: 'INR'
  }
}

curl -G https://api.recurso.dev/v1/analytics/dunning/overview \
  -H "Authorization: Bearer $API_KEY" \
  -d start_date=2026-06-01 \
  -d end_date=2026-06-30

const weights = await recurso.analytics.getDunningWeights();

// Response
{
  data: {
    weights: [
      { retry_number: 1, recovery_rate: 0.45, avg_days_after_failure: 1 },
      { retry_number: 2, recovery_rate: 0.25, avg_days_after_failure: 3 },
      { retry_number: 3, recovery_rate: 0.10, avg_days_after_failure: 7 }
    ]
  }
}

curl https://api.recurso.dev/v1/analytics/dunning/weights \
  -H "Authorization: Bearer $API_KEY"

const history = await recurso.analytics.getDunningHistory({
  start_date: '2026-06-01',
  end_date: '2026-06-30',
  limit: 50
});

// Response
{
  data: [
    {
      invoice_id: 'inv_042',
      customer_id: 'cust_abc',
      amount: 5899,
      retry_count: 2,
      status: 'recovered',
      first_failed_at: '2026-06-10T00:00:00Z',
      recovered_at: '2026-06-13T14:30:00Z'
    }
    // ...
  ]
}

curl -G https://api.recurso.dev/v1/analytics/dunning/history \
  -H "Authorization: Bearer $API_KEY" \
  -d start_date=2026-06-01 \
  -d end_date=2026-06-30 \
  -d limit=50