revenue.summary
Get total revenue, customers, orders, and key metrics like MRR, ARR, AOV, and LTV. View per-plan and per-product breakdowns with prior-period comparison for revenue trends.
Instructions
One call that returns the canonical revenue dashboard. Bundles every KPI tile + per-plan + per-product rollup + prior-period comparison into one round-trip. Use this for "how's revenue doing?" questions.
Returns:
total_revenueper currency (sum of every Money-typed property in the period)revenue— total in the dominant currency (a flat number)customers— distinct paying users (user_id when identified, else anonymous_id)orders— count of revenue events in the periodaov— revenue / ordersltv— mean cumulative revenue per paying customer to datemrr— running balance of mrr_delta through period end (null when not subscription-shaped)arr— mrr × 12 (null when mrr is null)is_subscription— true when any plan carries non-zero mrr_contribution OR the project's running MRR is non-zerohas_one_time— true when any non-subscription revenue event landed in the period (mixed sellers have both flags set)plans[]— per-plan rollup: revenue (in period), mrr_contribution (CUMULATIVE MRR balance per plan AT PERIOD END — forward-looking, not the in-period delta), customersproducts[]— per-product rollup: groups by the reservedproductproperty, falls back to event name when product isn't setcomparison— per-metric % change vs the prior period of equal length (revenue, customers, orders, aov, ltv, mrr, arr)
Examples:
"how's MRR this month" → period="30d", read
mrr+comparison.mrr.change"which plan has the most paying customers" → read
plans[], sort bycustomers"ARPU" →
revenue / customers(no top-level field; divide client-side)"top one-time products by revenue" → read
products[], already sorted desc"do we have any subscription customers" → read
is_subscription
Limitations: MRR/ARR/per-plan mrr_contribution require events to carry the reserved mrr_delta numeric property (set automatically by clamp.revenue() with billing="monthly" or "annual"). MRR is reported only in the project's dominant currency; multi-currency MRR is a future scope. customers uses user_id when present (clamp.identify() was called) and falls back to anonymous_id otherwise — counts are honest but can over-count if a paying customer uses two devices without identifying. For per-channel/per-campaign revenue, use revenue.sum with group_by + attribution_model="first_touch". For cohort retention with NRR, use revenue.retention.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| region | No | Administrative region inside a country (e.g. "California", "Bavaria"). Case-sensitive; must match the stored region exactly. Use traffic.breakdown(dimension="region") to discover values. | |
| city | No | City name (e.g. "San Francisco", "London"). Case-sensitive; must match the stored value. Use traffic.breakdown(dimension="city") to discover values. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| browser | No | Browser family (e.g. "Chrome", "Safari", "Firefox"). Use traffic.breakdown(dimension="browser") to discover the exact stored values. | |
| browser_version | No | Browser version string (e.g. "120.0"). Case-sensitive. | |
| os | No | Operating system family (e.g. "macOS", "iOS", "Windows", "Android"). Use traffic.breakdown(dimension="os") to discover stored values. | |
| os_version | No | OS version string (e.g. "14.2"). Case-sensitive. | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period | Yes | ||
| currency | Yes | ||
| revenue | Yes | ||
| customers | Yes | ||
| orders | Yes | ||
| aov | Yes | ||
| ltv | Yes | ||
| mrr | Yes | ||
| arr | Yes | ||
| is_subscription | Yes | ||
| has_one_time | Yes | ||
| total_revenue | Yes | ||
| comparison | Yes | ||
| plans | Yes | ||
| products | Yes |