get_transaction_breakdown

USD-normalized successful-payment totals split by plan, payment_provider, currency, or project. Includes share percent per group.

Purpose

Split USD-normalized successful-payment totals by one dimension for the requested window. Supported dimensions: plan, payment_provider, currency, project. Each group carries gross_usd, transactions, and share_percent so agents can answer "which provider drove the most revenue?" in one call.

Required ability

dashboard:read

Input schema

{
  "type": "object",
  "required": ["dimension"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Optional project UUID to scope the breakdown. Leave blank for all projects in the current team."
    },
    "dimension": {
      "type": "string",
      "description": "Required. Grouping dimension — plan, payment_provider, currency, or project."
    },
    "period": {
      "type": "string",
      "description": "Period preset — 7d, 14d, 30d, 60d, 90d, mtd, qtd, ytd, 1y, all. Defaults to 30d."
    },
    "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'."
    },
    "plan_ids": {
      "type": "array",
      "description": "Optional plan-UUID allow-list."
    },
    "statuses": {
      "type": "array",
      "description": "Optional SubscriptionStatus allow-list applied to parent subscriptions."
    },
    "payment_method_ids": {
      "type": "array",
      "description": "Optional payment-method UUID allow-list applied to parent subscriptions."
    }
  }
}

Output shape

{
  "data": {
    "total_gross_usd": "4821.50",
    "groups": [
      {
        "key": "stripe",
        "label": "Stripe",
        "gross_usd": "2891.00",
        "transactions": 110,
        "share_percent": 59.96
      }
    ]
  },
  "meta": {
    "period": "30d",
    "dimension": "payment_provider"
  }
}

Example prompts

"Break down last month's earnings by payment provider."

"Revenue by currency for project prj_01HX... year-to-date."

Failure modes

VALIDATION_FAILED — dimension is missing or not one of the allowed values.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks dashboard:read.