get_revenue_composition

The dashboards' donuts — fees by provider, transactions by plan kind, revenue by currency, payment outcomes and MRR by plan.

Purpose

Return how the window's revenue and payments are composed, as the five donuts the dashboards draw: transaction fees by payment provider, settled transactions by plan kind (subscription, one-time, lifetime, pass), gross revenue by currency in USD, payment attempts by outcome (succeeded, pending, failed) and, unwindowed because it is a balance, the monthly recurring revenue split by plan. The same figures GET /v1/analytics/composition returns. Every dataset carries total, unit (usd or count) and slices sorted largest first, each slice with its key, label, value, share_percent and chart color.

Required ability

dashboard:read

Input schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Optional project UUID to scope the figures. Leave blank for all projects in the current team."
    },
    "period": {
      "type": "string",
      "description": "Period preset — 7d, 14d, 30d, 60d, 90d, mtd, qtd, ytd, 1y, all. Defaults to 30d. MRR by plan ignores it: it is a balance, not a flow."
    },
    "from": {
      "type": "string",
      "description": "Explicit start date (ISO YYYY-MM-DD). Overrides period when paired with 'to'."
    },
    "to": {
      "type": "string",
      "description": "Explicit end date (ISO YYYY-MM-DD). Overrides period when paired with 'from'."
    }
  }
}

Output shape

{
  "data": {
    "range": { "from": "2026-08-13", "to": "2026-09-12" },
    "fees_by_provider": {
      "total": 84.1,
      "unit": "usd",
      "slices": [
        { "key": "stripe", "label": "Stripe", "value": 61.4, "share_percent": 73.01, "color": "blue" },
        { "key": "paypal", "label": "PayPal", "value": 22.7, "share_percent": 26.99, "color": "violet" }
      ]
    },
    "transactions_by_kind": {
      "total": 58,
      "unit": "count",
      "slices": [
        { "key": "subscription", "label": "Subscription", "value": 41, "share_percent": 70.69, "color": "blue" },
        { "key": "pass", "label": "Pass", "value": 17, "share_percent": 29.31, "color": "violet" }
      ]
    },
    "revenue_by_currency": {
      "total": 1682.0,
      "unit": "usd",
      "slices": [
        { "key": "USD", "label": "USD", "value": 1490.0, "share_percent": 88.59, "color": "blue" },
        { "key": "EUR", "label": "EUR", "value": 192.0, "share_percent": 11.41, "color": "violet" }
      ]
    },
    "payment_outcomes": {
      "total": 63,
      "unit": "count",
      "slices": [
        { "key": "succeeded", "label": "Succeeded", "value": 58, "share_percent": 92.06, "color": "emerald" },
        { "key": "failed", "label": "Failed", "value": 4, "share_percent": 6.35, "color": "rose" },
        { "key": "pending", "label": "Pending", "value": 1, "share_percent": 1.59, "color": "amber" }
      ]
    },
    "mrr_by_plan": {
      "total": 4120.0,
      "unit": "usd",
      "slices": [
        { "key": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "label": "Gold", "value": 2980.0, "share_percent": 72.33, "color": "blue" },
        { "key": "0c1e7a54-2f6b-4d8e-9a3c-1b5d7e9f2a46", "label": "Silver", "value": 1140.0, "share_percent": 27.67, "color": "violet" }
      ]
    }
  },
  "meta": { "period": "30d", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13" }
}

Example prompts

"Where did the transaction fees go last month, by payment provider?"

"How many charges failed this quarter, and which plans carry the MRR?"

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks dashboard:read.

get_dashboard_metrics
get_transaction_breakdown — gross revenue grouped by one dimension.
get_plan_performance
Analytics API