Metric catalog
Every metric Meerkats can report, query or watch, by family, with its definition and source.
The metric catalog is the list of every metric your workspace can report, query, chart or watch, with its definition and the dimensions it can be grouped by. Each metric is defined once in the semantic layer, so a rule, a chart, an agent’s answer and an API query all return the same number for the same question.
This page groups the catalog by family and says where each metric comes from. In the app, About these numbers (the info icon on Cockpit) shows the definitions of the metrics on that screen. Over the API, GET /metrics/catalog returns your workspace’s catalog with the groupable dimensions for each metric.
How to read the catalog#
- Platform metrics are shown under the platform’s own label on that platform’s tables, with the formula and attribution basis in the tooltip. Underneath, one canonical metric.
- Blended metrics belong to no platform: revenue from your order ledger, spend from platform billing. They always print their formula.
- Derived metrics carry a derived badge. TACOS, for example, never appears without “(calculated)”.
- Availability depends on what you have connected. A metric whose source isn’t connected is in the catalog but reports no data, and says why.
Dimensions read as entity__attribute: ad_row__platform, ad_row__campaign, order__channel, product__sku, metric_time__day, metric_time__week. Not every metric supports every dimension; the catalog lists the valid ones, and a query with an invalid pair is rejected rather than guessed.
Delivery and cost#
| Metric | Definition | Source |
|---|---|---|
| Spend | What the platform billed for the period | All ad platforms |
| Impressions | Times the ad was shown | All ad platforms |
| Reach | Unique people who saw the ad | Meta, TikTok |
| Frequency | Impressions ÷ reach | Meta, TikTok |
| CPM | Spend ÷ impressions × 1,000 | All ad platforms |
| Clicks | Clicks on the ad (Meta: link clicks) | All ad platforms |
| CTR | Clicks ÷ impressions × 100 | All ad platforms |
| CPC | Spend ÷ clicks | All ad platforms |
| Impression share | Impressions won ÷ eligible impressions (Search) | Google, Microsoft |
| Lost IS (budget), Lost IS (rank) | Eligible impressions lost to budget or to Ad Rank | Google, Microsoft |
| Quality score | 1 to 10 keyword relevance estimate, with its three components | Google, Microsoft |
| Invalid clicks | Clicks the platform filtered and did not charge |
Conversions and value#
| Metric | Definition | Source |
|---|---|---|
| Conversions | Count of the conversion actions that count (Google: 'include in Conversions') | Google, Microsoft, TikTok |
| Purchases | Purchase events attributed to the ad | Meta, TikTok |
| Purchase value / Conversion value | Revenue of attributed purchases on the platform's basis | Meta, Google, TikTok |
| Attributed orders, units, sales | Marketplace orders, units and sales attributed to ads, in 1, 7, 14 or 30-day windows | Amazon, Flipkart, Walmart |
| Cost per purchase / Cost per conversion | Spend ÷ purchases or conversions | Meta, Google, TikTok |
| Leads, Cost per lead | Lead events and instant forms; spend ÷ leads | Meta, Google, TikTok |
| Conversion rate | Conversions ÷ clicks × 100 | All ad platforms |
| View-through conversions | Conversions after an impression with no click | Google, Amazon (SD) |
Attribution is part of the definition
Platform conversions are counted on each platform’s basis: Meta 7-day click and 1-day view by default; Google by click date with up to 90 days of lag; Flipkart 28-day click or 7-day view; Amazon 7 or 14 days by ad type. Two metrics with different bases are different metrics. See the semantic layer.Efficiency#
| Metric | Definition | Source |
|---|---|---|
| Platform ROAS | The platform's own return on spend, shown under its own label: Purchase ROAS (Meta), Conv. value / cost (Google), ROI (Flipkart), ROAS (Amazon) | All ad platforms |
| Real ROAS | Revenue from your own orders matched to clicks by click ID or UTM, ÷ spend | Meta, Google, TikTok, Microsoft (needs a store) |
| ROAS gap | Platform ROAS ÷ real ROAS | Same |
| ACOS | Spend ÷ attributed sales × 100 (lower is better) | Amazon, Walmart |
| TACOS | Total ad spend ÷ total revenue × 100 | Marketplaces with seller data; blended |
| MER | Total revenue ÷ total ad spend, whole business | Blended |
| Blended CAC | Total ad spend ÷ new customers | Blended |
| New-customer ROAS | Revenue from first-time customers ÷ total ad spend | Blended |
Platforms are never ranked against each other on their own ROAS. Cross-platform comparison uses real ROAS where a store is connected, marketplace orders where it isn’t, and MER at workspace level.
Sales and margin#
| Metric | Definition | Source |
|---|---|---|
| Gross sales, Net sales | Order value before and after discounts, refunds and cancellations | Shopify, marketplaces |
| Orders | Orders by order date | Shopify, marketplaces |
| AOV | Revenue ÷ orders | Shopify, marketplaces, blended |
| New vs returning | Split of orders and revenue by first-order customers vs repeat | Shopify |
| Refunds, Cancellations | Kept as separate streams | Shopify, marketplaces |
| Discounts | Discount value and orders by code or automatic discount | Shopify |
| Gross margin | Net revenue minus cost per item | Shopify (needs cost per item) |
| CM1, CM2, CM3 | Margin after product cost; after fees, shipping and RTO; after marketing | Blended (needs fees and shipping) |
| Payment success rate | Captured ÷ attempted payments | Razorpay |
| Settled amount, Fees | What reached the bank, and what was deducted | Razorpay, Amazon, Flipkart |
| RTO rate | Return-to-origin orders ÷ COD orders | Marketplaces, Shopify (COD) |
Customers and funnel#
| Metric | Definition | Source |
|---|---|---|
| Repeat rate | Share of a cohort placing a second order within N days | Shopify, marketplaces |
| LTV | Cumulative gross profit per customer at 30, 60, 90, 180 days | Shopify (needs cost per item) |
| CAC payback | Months for a customer's gross profit to repay acquisition cost | Blended |
| Retention rate | Share of a cohort still buying in month N | Shopify |
| Sessions, Users | Site traffic by source, medium, campaign, landing page | GA4, Shopify pixel |
| Add-to-cart rate, Checkout rate | Add to cart ÷ product views; checkout ÷ add to cart | GA4, Shopify pixel |
| Pipeline value, Win rate, Sales cycle | Open deal value; won ÷ closed; days from create to close | HubSpot, Salesforce |
Stock and competition#
| Metric | Definition | Source |
|---|---|---|
| Units on hand | Stock per product, summed over the locations you chose | Shopify, Amazon FBA, Flipkart FBF, sheets |
| Days of cover | Units on hand ÷ average daily units sold (14-day default) | Same |
| OOS ad waste | Live ad spend on products that are out of stock or at risk | Any ad platform + a stock source |
| Availability % | Share of city-store slots where the SKU is in stock | Blinkit, Zepto, Instamart |
| Price position | Your per-unit price ÷ median rival per-unit price | Competitor tracking |
| Rating gap, Review count gap | Your rating and reviews vs the paired rival listing | Competitor tracking |
| Share of voice | Your share of top results across tracked search terms | Competitor tracking |
Query a metric#
Any metric in the catalog can be queried with any of its dimensions, over any date range.
GET /metrics/catalog
→ { "success": true, "vertical": "ecommerce",
"metrics": { "<metric>": ["<dimension>", …], … } }In the app, ask the chat box on Cockpit; in Claude, ask over the MCP server. All three run the same query.
Add your own metric#
You can define metrics the catalog doesn’t have: a contribution margin using your real fee schedule, a blended CAC that excludes brand spend, a conversion rate for one funnel step. A custom metric has the same four parts as any other (measures, formula, dimensions, basis) and is versioned: a report from before the change still shows the definition in force then. Ask the agent “define a metric called…” and it drafts the definition for you to confirm, or define it under the metric catalog in Data Hub.