Skip to main content

​
MRR analytics

GET /v1/analytics/mrr is the single place to read monthly recurring revenue (MRR) out of MarginFront. It returns one of three MRR variants, or all three at once. Use it when you need to answer:
  • “What did we actually bill for last month?”
  • “If the last 30 days kept going, what would we bill per month?”
  • “What is the contractual floor we will bill regardless of usage?”
  • “How does a single customer (or subscription) contribute to each of those?”
Each variant answers a different question. They can and do produce different numbers. Pick the one that matches what you are trying to show. This is a read-only endpoint.

​
The endpoint

Method and URL: 
GET /v1/analytics/mrr
Auth: API key in the x-api-key header.

​
Query parameters

ParamTypeRequiredDescription
variantstringnoWhich MRR variant to return. One of canonical, runRate, committed, all. Default: canonical.
customerIdUUIDnoNarrow to one customer. Use MarginFront’s internal customer UUID, not your externalId.
subscriptionIdUUIDnoNarrow to one subscription.

​
The three MRR variants

​
canonical (last-calendar-month billed)

Plain English: “What did we actually bill last calendar month?” Looks at non-draft invoices whose invoice date lands in the most recent complete calendar month. Sums the totals. That is your MRR. This is a backward-looking number based on what finance actually sent out. Good for: finance reporting, board decks, anything where “actual billed” is what you want.

​
runRate (last 30 days, monthly-normalized)

Plain English: “If the current pace keeps going, what would we bill per month?” For each active subscription: take recurring fees plus seat fees plus actual usage from the last 30 days, and normalize everything to a monthly number (yearly subs get divided by 12). Add it up across every active subscription. That is run-rate MRR. Good for: forecasting, growth dashboards, anything where you want the forward-looking trajectory.

​
committed (contractual floor)

Plain English: “What will we bill per month even if usage goes to zero?” Same shape as run-rate, but actual usage is replaced with the subscription’s minimumCommitment times its rate (zero if no minimum is set). So it strips out variability and shows only what is guaranteed by contract. Good for: revenue predictability, churn-risk analysis, anything where you want to see the floor.

​
all

Returns all three variants in one response. Use this when you need to render a comparison (e.g., a dashboard tile showing all three side by side).

​
Example curl calls

Last calendar month’s billed MRR (default): 
curl "https://api.marginfront.com/v1/analytics/mrr" \
  -H "x-api-key: mf_sk_test_..."
Run-rate MRR for one customer: 
curl "https://api.marginfront.com/v1/analytics/mrr?variant=runRate&customerId=bc8eceda-50e4-4138-b2a2-47e92d344540" \
  -H "x-api-key: mf_sk_test_..."
All three variants at once: 
curl "https://api.marginfront.com/v1/analytics/mrr?variant=all" \
  -H "x-api-key: mf_sk_test_..."

​
What you get back (200 OK)

​
variant=canonical

{
  "variant": "canonical",
  "mrr": 12480.75,
  "arr": 149769.0
}
  • mrr is last calendar month’s non-draft invoice total.
  • arr is mrr × 12.

​
variant=runRate

{
  "variant": "runRate",
  "mrr": 13842.5,
  "breakdown": [
    {
      "subscriptionId": "9a8b7c6d-...",
      "customerId": "5e7f8a3d-...",
      "agentId": "b47e12fa-...",
      "planId": "a1b2c3d4-...",
      "recurring": 299.0,
      "seatBased": 50.0,
      "usage": 493.5,
      "total": 842.5
    }
  ]
}
  • mrr is the sum of total across every active subscription.
  • breakdown is one row per active subscription.
  • recurring is the recurring-fee contribution, monthly-normalized (yearly subs divided by 12).
  • seatBased is the seat-fee contribution: max(seatsCount, minimumCommitment) × rate, monthly-normalized.
  • usage is actual last-30-days usage revenue for the subscription.
  • total is recurring + seatBased + usage (the sub’s run-rate MRR contribution).

​
variant=committed

{
  "variant": "committed",
  "mrr": 10948.0,
  "breakdown": [
    {
      "subscriptionId": "9a8b7c6d-...",
      "customerId": "5e7f8a3d-...",
      "agentId": "b47e12fa-...",
      "planId": "a1b2c3d4-...",
      "recurring": 299.0,
      "seatBased": 50.0,
      "usage": 200.0,
      "total": 549.0
    }
  ]
}
Same fields as runRate, but usage is replaced with the strategy’s contractual floor (minimumCommitment × rate, or 0 if no minimum is set).

​
variant=all

{
  "variant": "all",
  "canonical": {
    "mrr": 12480.75,
    "arr": 149769.0
  },
  "runRate": {
    "mrr": 13842.5,
    "breakdown": []
  },
  "committed": {
    "mrr": 10948.0,
    "breakdown": []
  }
}
All three variants nested under one response. All money fields are number, not strings.

​
When to use this vs. other endpoints

Use this endpoint when you specifically want MRR or ARR. Use /v1/analytics/revenue when you want revenue for an arbitrary window (not a monthly roll-up), with cost and margin attached. Use /v1/invoices when you want the individual invoice records that make up the canonical MRR total.

​
Using the Node SDK

import { MarginFrontClient } from "@marginfront/sdk";

const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

// Last calendar month's billed MRR
const { mrr, arr } = await mf.analytics.mrr();
console.log(`MRR: $${mrr}, ARR: $${arr}`);

// Run-rate MRR with per-subscription breakdown
const runRate = await mf.analytics.runRateMrr();
console.log(`Run-rate MRR: $${runRate.mrr}`);
for (const row of runRate.breakdown) {
  console.log(`  sub ${row.subscriptionId}: $${row.total}/mo`);
}

// Committed MRR (contractual floor)
const committed = await mf.analytics.committedMrr();
console.log(`Committed floor: $${committed.mrr}`);
See the SDK analytics page for all seven analytics methods.

​
Common errors

  • 400 Bad Request: variant is not one of canonical, runRate, committed, all, or a UUID filter is invalid.
  • 401 Unauthorized: API key missing or wrong.