Analytics

MRR, churn rate, customer growth, subscription breakdown, and webhook statistics

Get Analytics

GET /api/billstack/teams/{teamId}/projects/{projectId}/analytics?growthDays=30

Returns a comprehensive analytics snapshot for the project.

Query Parameters:

Parameter	Type	Default	Description
`growthDays`	`number`	`30`	Number of days for growth/trend calculations

Example:

curl "https://your-billstack.com/.../analytics?growthDays=30" \
  -H "Authorization: Bearer bs_..."

Response:

{
  "mrr": 12500.00,
  "customerCount": 450,
  "churnRate": 3.2,
  "subscriptionBreakdown": {
    "active": 420,
    "trialing": 20,
    "past_due": 10,
    "canceled": 45,
    "unpaid": 2,
    "incomplete": 1,
    "paused": 0
  },
  "customerGrowth": [
    { "date": "2026-03-01", "count": 430 },
    { "date": "2026-03-08", "count": 438 },
    { "date": "2026-03-15", "count": 445 },
    { "date": "2026-03-22", "count": 448 },
    { "date": "2026-03-30", "count": 450 }
  ],
  "webhookStats": {
    "total": 1200,
    "processed": 1198,
    "failed": 2
  },
  "referralStats": {
    "totalCodes": 50,
    "totalReferrals": 120,
    "converted": 95
  }
}

Auth: Read access (session or API key with analytics:read).

Response Fields

`mrr` (number)

Monthly Recurring Revenue in the project's base currency. Calculated from all active and trialing subscriptions:

Monthly prices are counted at face value
Yearly prices are divided by 12
Weekly prices are multiplied by ~4.33
One-time prices are excluded

`customerCount` (number)

Total number of customers in the project.

`churnRate` (number)

Percentage of subscriptions that canceled in the growthDays period relative to total active subscriptions at the start of that period.

churnRate = (canceled in period / active at start of period) * 100

`subscriptionBreakdown` (object)

Count of subscriptions by status:

Status	Description
`active`	Current and paid
`trialing`	In free trial
`past_due`	Payment failed, retrying
`canceled`	Ended
`unpaid`	All retries exhausted
`incomplete`	First payment pending
`paused`	Paused (if enabled)

`customerGrowth` (array)

Time series of total customer count, sampled at regular intervals over the growthDays period. Useful for plotting growth charts.

`webhookStats` (object)

Field	Description
`total`	Total webhook events received for this project
`processed`	Successfully processed events
`failed`	Events that failed processing

`referralStats` (object)

Field	Description
`totalCodes`	Total referral codes created
`totalReferrals`	Total times codes were used
`converted`	Referrals where the referee subscribed

Usage Example

Build a dashboard widget that displays key metrics:

async function loadDashboard() {
  const res = await fetch(`${BILLSTACK_URL}/.../analytics?growthDays=30`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` },
  });
  const data = await res.json();

  return {
    mrr: `$${(data.mrr / 100).toFixed(2)}`,
    customers: data.customerCount,
    churn: `${data.churnRate.toFixed(1)}%`,
    activeSubscriptions: data.subscriptionBreakdown.active,
    webhookHealth: `${((data.webhookStats.processed / data.webhookStats.total) * 100).toFixed(1)}%`,
  };
}

Analytics

On this page