> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Understanding Nerve Centre KPI cards and card types
> Each Nerve Centre KPI card is a named metric with a chart type and alert trigger. Learn how Key Metrics, Supporting Metrics, and Cross-Platform Metrics types work.
A card is the unit of work inside the Nerve Centre. Each card represents one question asked of one data source over one defined time window - for example, "Shopify Total Revenue, last 30 days versus the prior 30 days" or "Google Ads Zero-Conversion Spend, last 30 days". The card is the smallest object that has a stable identity, a stable query, and a stable visual treatment. The merchant trusts a card the same way they trust a row in a financial report: same definition every day, same window logic every day, same colour rules every day.
A card is not a chart. A chart is one of the things a card can render. A card is the wrapper: identity, metadata, query binding, render rules, alert binding, and sentiment binding.
## Metrics types
The cards in the Nerve Centre catalogue are classified into three metrics types.
### Key Metrics cards
Key Metrics cards answer the questions you ask of a connector on a typical day - not weekly, not quarterly, but daily. They are editorially curated by the Vortex IQ product team in collaboration with the merchant base, capped at roughly 15 percent of each connector's card set.
A metric becomes a Key Metric after two checks:
1. **Universality** - does every merchant on this connector ask this question regularly?
2. **Decision impact** - does the answer change what the merchant does today?
Key Metrics cards render in a larger tile at the top of each category group. They carry a coloured accent border that picks up the card's sentiment colour. They surface in the Executive view (the cross-connector morning scan) and lead every scheduled briefing.
**Example Key Metrics cards per connector:**
* **Shopify** - Total Revenue, Order Count, Refund Rate, AOV, Conversion Rate
* **Stripe** - Authorisation Rate, Successful Charges, Decline Rate by Reason
* **Google Ads** - ROAS, Spend, Cost per Acquisition, Zero-Conversion Spend, Wasted Spend
* **Klaviyo** - Active Subscribers, Open Rate, Click Rate, Revenue Per Recipient
* **Datadog** - Checkout Latency p95, Error Rate, Open Incidents
### Supporting Metrics cards
Supporting Metrics cards are the long-tail breakdowns that fill out each connector's card set: ROAS by Campaign, Spend by Device, Conversions by Hour, CPC by Region, and hundreds more. Supporting does not mean unimportant - a merchant investigating a performance drop needs the breakdowns. What changes is the visual treatment: smaller tiles in the secondary grid, excluded from the Executive view by default, snapshotted weekly rather than daily in Vortex Memory.
### Cross-Platform Metrics cards
Cross-Platform Metrics cards join data from two or more connectors to compute a value that no single connector could produce alone. The card's `cross_channel` flag is `true` and the `derive_from` field lists the source connectors. Examples:
* **Active Ads on Out-of-Stock SKUs** (`derive_from: [google_ads, shopify]`) - for each SKU advertised in Google Ads in the last 24 hours, what is the current Shopify inventory level? When spend > 0 and inventory == 0, you are paying for clicks on out-of-stock product.
* **Revenue at Risk from active incidents** (`derive_from: [stripe, shopify]`) - joins Stripe decline spikes with Shopify refund spikes inside the same window to surface payment-vendor incidents before they appear in your support queue.
* **LCP-to-Conversion Correlation** (`derive_from: [website_performance, google_analytics]`) - maps Largest Contentful Paint scores to session conversion rates by landing page.
Cross-Platform Metrics cards are roughly 4 to 7 percent of the catalogue and render in a larger tile with a distinctive connecting-lines icon. Clicking a Cross-Platform Metrics card routes you into the corresponding Vortex Mind diagnostic report.
## Card categories
Within each connector's tab, cards are grouped by **category**. The categories mirror the way the vendor's own admin presents its data, so the metric you know from Google Ads or Shopify's own dashboard sits in the same logical place inside the Nerve Centre.
Common categories across connectors:
| Category | What you find there |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| Executive Overview | Headline KPIs: total revenue, total spend, ROAS, CPA trend |
| Alerts & Anomalies | Cards that fire when something breaks: Conversion Drop Alert, CPC Spike, Spend Anomaly, Zero-Conversion Spend |
| Campaign Performance | Revenue, ROAS, CTR, and CPC broken down by individual campaign |
| Budget Monitoring | Spend vs Budget, Budget Utilisation gauge, Overspending and Underspending Campaigns |
| Funnel & Conversion | Conversion funnel, conversion lag, conversion rate by campaign and device |
| Keyword Intelligence | Wasted Spend, Top Keywords by Spend and Conversions, Quality Score Distribution |
| Device Performance | ROAS, CPC, CTR, and conversion rate broken down by device type |
| Geography Performance | Conversions, spend, and revenue by country, region, and city |
| Day & Time Performance | Conversions by hour (heatmap), spend by day of week, CPC by hour |
| Landing Page Performance | CPC, conversion rate, and revenue broken out by landing page URL |
## Chart types
Each card renders one of the following chart types, chosen to match the shape of the data:
| Chart type | Used for |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kpi` | Single scalar value with trend arrow and sentiment colour. Used for Key Metrics headline metrics (Total Revenue, Total Spend, Zero-Conversion Spend). |
| `gauge` | Percentage or rate within a defined range. Used for Budget Utilisation, ROAS (as a level indicator), Authorisation Rate. |
| `sparkline` | Compact trend line showing direction over the time window. Used for ROAS Trend, CPC Trend, Conversions Trend. |
| `area` | Filled time-series showing volume over time. Used for Spend Over Time, Revenue Over Time. |
| `bar` | Vertical bar chart for categorical comparisons over time. Used for Conversions by Day of Week, Spend by Hour. |
| `bar_horizontal` | Horizontal bar chart for ranked categorical breakdowns. Used for ROAS by Campaign, Revenue by Campaign, CPC by Region. |
| `line` | Time-series line. Used for CPC by Hour. |
| `donut` | Part-to-whole distribution. Used for Conversions by Device, Spend by Device, Conversion Actions Breakdown. |
| `funnel` | Step-by-step drop-off visualisation. Used for Conversion Funnel. |
| `table` | Ranked row data. Used for Campaign Comparison, Top Keywords by Spend, Landing Page Performance. |
| `heatmap` | Two-dimensional intensity grid. Used for Conversions by Hour (day-of-week × hour-of-day). |
| `geo_map` / `choropleth` | Geography heat map. Used for Conversions by Country, Spend by Country. |
| `progress` | Linear progress bar showing spend relative to budget cap. Used for Spend vs Budget. |
| `dual_axis` | Two series on a shared time axis with separate Y scales. Used for Clicks vs Conversions. |
| `alert_list` | Structured alert feed. Used for real-time alert cards (ROAS Drop Alert, CPC Spike Alert). |
| `scatter` | Two-axis correlation plot. Used for LCP-to-Conversion cross-platform cards. |
## Real card examples
### ROAS (Google Ads) - Key Metrics
The ROAS card (`gads_roas`) is a `gauge` chart in the Executive Overview category. It displays Return on Ad Spend - revenue divided by ad spend - for the selected time window compared to the prior comparable period. Across most ad-platform connectors (AdRoll, Amazon Ads, Meta Ads, LinkedIn Ads, TikTok Ads, Microsoft Ads, and others), ROAS is consistently a Key Metrics card because it is the primary signal of whether paid acquisition is profitable.
ROAS of 4.0× means £4 of revenue per £1 of ad spend. Below 2.0× is unprofitable for most direct-to-consumer brands after accounting for cost of goods, fulfilment, and overheads.
### Zero-Conversion Spend (Google Ads) - Key Metrics, `gads_zero_conversion_spend`
This `kpi` card surfaces the total spend on enabled campaigns that produced **zero primary conversions** over the last 30 days. The formula sums `cost_micros ÷ 1,000,000` for every campaign where `metrics.conversions = 0` and `campaign.status = ENABLED`. The alert fires at any non-zero value; an action prompt fires at spend above the threshold (default: \$500 per 30-day window).
A worked example from the source data: a UK fashion brand with £27,400 total Google Ads spend had £680 of zero-conversion spend across two campaigns - a Display Remarketing campaign with too-small an audience (£420) and a mismatched "vintage 90s" search campaign (£260). Pausing both was a five-minute action recovering 2.5 percent of total spend.
### ROAS Drop Alert (Google Ads) - Key Metrics, `gads_alert_roas_drop`
An `alert_list` card with `data_type: Real-time`. The alert fires when today's ROAS drops more than 25 percent versus the average of the same day-of-week over the prior seven days. The card is suppressed before 14:00 local time to avoid false positives from incomplete morning data. It sits alongside Conversion Drop Alert and CPC Spike Alert as the first-responder cards for a Google Ads account going wrong.
## Card metadata
Every card carries a fixed metadata shape used by the Nerve Centre renderer, the alert engine, Vortex Mind, Ask Viq, and the documentation generator. Key fields:
| Field | Example | Purpose |
| --------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `id` | `gads_zero_conversion_spend` | Stable identifier. Persists across label renames. |
| `label` | "Zero-Conversion Spend" | Human-readable name shown on the tile. |
| `category` | "Alerts & Anomalies" | The group the card sits under in the connector tab. |
| `chart_type` | `kpi` | How the card renders. |
| `time_window` | `30D`, `7D`, `RT` | Default lookback for the card. |
| `alert_trigger` | `">$0 (any campaign with spend, no conv)"` | The condition that fires an alert. |
| `sentiment_key` | `zero_conversion_spend` | The colour rule used to mark the value green, amber, or red. |
| `tier` | `hero` or `standard` | Metrics type for dashboard prominence: `hero` shows as **Key Metrics**, `standard` shows as **Supporting Metrics**. |
| `roles` | `[owner, marketing, finance]` | Who the card is for; drives alert routing. |
| `data_type` | `API-derived`, `Real-time`, `Native` | Where the data comes from and how it refreshes. |
## Navigating to a connector's cards
Click **Nerve Centre** in the left navigation. The connector tab row appears at the top of the dashboard.
Click the tab for the connector you want - for example, Google Ads, Shopify, or Klaviyo. If the connector is not yet connected, the tab shows a "Connect to unlock" placeholder.
Cards are grouped by category. Expand any category group to see all cards in it. Use the **Key Metrics only** filter (top-right) to collapse the view to Key Metrics cards only.
Click the info icon on any card tile to open its documentation page. The doc page covers the metric definition, calculation formula, source field trace, worked example, sibling cards, and FAQs.
Use the **Executive view** toggle (dashboard header) to see Key Metrics and Cross-Platform Metrics cards across every connected connector at once. This is the fastest way to spot which connectors have active alerts or amber metrics.