Free tool

Write one KPI definition your dashboards can agree on

When two dashboards disagree, it is usually two definitions sharing one name. Fill in the thirteen fields that decide what a metric means (owner, formula, grain, sources, who counts, the window and the timezone), start from blank or from an illustrative example, and export it as Markdown for your docs, CSV for a spreadsheet, or a printout for the meeting that approves it.

By Luís Pereira · Everything stays in your browser · No sign-up, no account

The live preview and the exports need JavaScript. The blank template and both examples are written out below, and the blank template downloads as CSV without it.

Metric name

The exact name it will carry in every dashboard. One name, one definition: if two numbers need to exist, give them two names.

Business question / decision

The decision this number informs. A metric nobody decides anything with does not need a definition, it needs deleting.

Accountable owner

The one person (a role is fine) who approves the definition and any change to it. Not the person who builds it.

Formula, in plain words

What is counted or summed, and what is subtracted, written so the business owner can check it without reading SQL.

Unit

Currency and whether tax is in or out, a count of what (accounts, users, orders), or a ratio of what to what.

Grain

What one row stands for before it is added up, and the levels it may be reported at (day, month, country, channel).

Source tables / events

The tables, columns and events it is built from, and which system is the source of truth when they disagree.

Included population

Which orders, customers or events count. Name the qualifying status or action rather than “all valid ones”.

Excluded population

What is deliberately left out: test and internal records, cancellations, fraud, channels reported elsewhere.

Reporting window

Calendar or rolling, which date decides the period (ordered, paid, shipped, refunded), and whether closed periods are ever restated.

Timezone

The timezone that decides which day an event belongs to. UTC and the business’s local time disagree around every midnight.

Freshness expectation

When yesterday’s number is complete and safe to read, and what late-arriving data does to it.

Known caveats

Gaps, approximations and known differences from other reports, with the size of the difference where you know it.

Nothing you type is sent anywhere, put in the page address or saved: reloading clears it. The exports contain exactly what the preview shows.

Why it matters

Same tables, two plausible definitions, two answers

Illustrative figures, not client data. Net revenue for October. October’s completed orders total €120,000. €5,000 of refunds were issued in October on October orders, €4,000 in October on September orders, and €3,000 in November on October orders.

Definition	Rule	Working	Net revenue
Definition A: refunds belong to the month they are issued	Subtract every refund issued in October.	€120,000 − €5,000 − €4,000	€111,000, final when October closes
Definition B: refunds belong to the month of the original order	Subtract every refund on an October order, whenever it was issued.	€120,000 − €5,000 − €3,000	€112,000 by the end of November, and it can still move later

Neither team is wrong, and both numbers come from the same tables. Until the refund timing is written down and approved, the finance pack and the product dashboard will disagree every month, and someone will be asked to “fix” whichever one is in front of them.

Template

The blank KPI definition template

The same thirteen fields as the builder, with what to write in each. Print this page or download the blank template as CSV to fill it in a spreadsheet.

Field	What to write	Definition
Metric name	The exact name it will carry in every dashboard. One name, one definition: if two numbers need to exist, give them two names.
Business question / decision	The decision this number informs. A metric nobody decides anything with does not need a definition, it needs deleting.
Accountable owner	The one person (a role is fine) who approves the definition and any change to it. Not the person who builds it.
Formula, in plain words	What is counted or summed, and what is subtracted, written so the business owner can check it without reading SQL.
Unit	Currency and whether tax is in or out, a count of what (accounts, users, orders), or a ratio of what to what.
Grain	What one row stands for before it is added up, and the levels it may be reported at (day, month, country, channel).
Source tables / events	The tables, columns and events it is built from, and which system is the source of truth when they disagree.
Included population	Which orders, customers or events count. Name the qualifying status or action rather than “all valid ones”.
Excluded population	What is deliberately left out: test and internal records, cancellations, fraud, channels reported elsewhere.
Reporting window	Calendar or rolling, which date decides the period (ordered, paid, shipped, refunded), and whether closed periods are ever restated.
Timezone	The timezone that decides which day an event belongs to. UTC and the business’s local time disagree around every midnight.
Freshness expectation	When yesterday’s number is complete and safe to read, and what late-arriving data does to it.
Known caveats	Gaps, approximations and known differences from other reports, with the size of the difference where you know it.

Examples

Two illustrative KPI definitions

Illustrative, not a standard. These show the level of detail a definition needs; they are not the right definition of net revenue or active customers for your business. Each lists the assumptions another team could reasonably make differently. Both load into the builder above.

Net revenue illustrative

Assumptions made explicit

Refunds reduce the month they are issued in, so a closed month never changes.
Sales tax and VAT are excluded; shipping charged to the customer is included.
Foreign currency is converted at the order date’s daily rate, not the month-end rate finance may use.
Days are cut in the business’s local timezone, not UTC.

Business question / decision: How much revenue did we keep this month after refunds? Used in the monthly performance review against the plan, and to decide whether to change the marketing budget for the next month.
Accountable owner: Head of Finance (illustrative)
Formula, in plain words: Sum of the order value of completed orders in the period, excluding sales tax and VAT, minus the value of refunds issued in the period, whichever month the original order was in.
Unit: EUR, excluding tax. Other currencies converted at the order date’s daily rate.
Grain: One row per order (and one per refund) per day. Reported by day and calendar month, and by sales channel.
Source tables / events: orders: order_id, status, completed_at, gross_amount, tax_amount, currency refunds: refund_id, order_id, refunded_at, amount fx_rates: daily rate per currency The payment provider’s settlement report is the source of truth when they disagree.
Included population: Orders with status "completed", from all sales channels, including orders paid with gift cards.
Excluded population: Test orders and staff orders; orders cancelled before payment; B2B invoices raised directly in the ERP (reported in "B2B revenue").
Reporting window: Calendar month, by completed_at for orders and refunded_at for refunds. Closed months are not restated.
Timezone: Europe/Lisbon (the business’s reporting timezone)
Freshness expectation: Yesterday is complete by 07:00. The month is final once finance closes it, on the 3rd working day.
Known caveats: Illustrative assumptions, not a standard. Refunds on last month’s orders lower this month, so the figure differs from a report that restates refunds to the order month. Finance converts at the month-end rate, so its total differs slightly in months with large FX moves.

Active customers illustrative

Assumptions made explicit

An account counts, not a user or a device: three people in one company are one customer.
Only actions that show the product being used qualify. Logging in, opening an email or an API sync does not.
The window is a calendar month, not a rolling 28 or 30 days.
Trial accounts count; internal and test accounts do not.

Business question / decision: How many customers got value from the product this month? Used to track retention month to month and to decide where the customer success team spends its time.
Accountable owner: Head of Product (illustrative)
Formula, in plain words: Count of distinct customer accounts with at least one qualifying action in the calendar month. Qualifying actions: created a report, edited a report, shared a report.
Unit: Count of customer accounts (not users, not devices)
Grain: One row per account per month. Reported by month, plan and country.
Source tables / events: product_events: account_id, event_name, occurred_at accounts: account_id, status, plan, is_internal The accounts table is the source of truth for which accounts exist.
Included population: Paying and trial accounts with at least one qualifying action in the month.
Excluded population: Accounts whose only activity is logging in, opening emails or automated API syncs; internal and test accounts (is_internal = true); accounts deleted before month end.
Reporting window: Calendar month, by occurred_at. Not a rolling window.
Timezone: UTC
Freshness expectation: Events arrive within two hours. A month is complete at 06:00 UTC on the 1st of the next month.
Known caveats: Illustrative assumptions, not a standard. Adding or removing a qualifying action changes history: restate past months, or note the date of the change. Merged accounts are counted once, under the surviving account.

Handoff

Before the definition is final

Have the business owner approve it. The accountable owner reads the definition, not the SQL, and approves it in writing, with the date. Until then it is a draft.
Compare source, model and report totals. For the same population and the same period, put the total from the source system, the modelled table and the dashboard side by side.
Document every explained difference. Each gap gets a cause and a size: timezone, refund timing, late data, an excluded channel. A gap with no explanation is a bug, not a caveat.
Assign an owner for future changes. Name who approves a change to the definition, and record each change with its date, so a jump in the chart can be traced to a decision.

Totals still do not reconcile, or two teams cannot agree? That is the work the analytics engineering engagement starts with: every version of the contested metric side by side with its numbers, the business owner choosing, and one definition coded once.

Talk through the disagreement

Method

What this does, and what it does not

It follows the first two steps of the analytics engineering process: put the differences between versions of a metric in front of the people who own them, then write one definition down and get it signed off before it is coded.
The fields are the choices that, left implicit, make two correct queries return different numbers: population, window, the date that decides the period, timezone, unit and freshness.
The exports carry the same fields and text as the preview. Line breaks are kept, and the CSV quotes any value with a comma, quote or line break, so it opens cleanly in Sheets or Excel.

What it does not do. One definition at a time. It does not generate SQL or dbt models, connect to your warehouse or BI tool, or store definitions for a team; there are no accounts. It cannot tell you which definition is right, only make sure the choice is written down and owned.

Questions

KPI definitions

What should a KPI definition include?

At least: the exact name, the decision it informs, one accountable owner, the formula in plain words, the unit, the grain, the source tables or events, who is included and excluded, the reporting window and the date that decides it, the timezone, when the number is complete, and the known caveats. Most disagreements between dashboards come from the last six, which is why this template asks for them explicitly rather than leaving them to whoever writes the SQL.

Why do two dashboards show different numbers for the same metric?

Usually because they are two definitions with one name. Refunds counted when issued in one and against the original order in the other, UTC in one and local time in the other, test accounts excluded in one and not the other. Each choice is defensible, and each moves the number. Writing the choices down, with one owner approving them, turns a recurring argument into a documented decision.

Who should own a KPI definition?

The person accountable for the decision the number informs, usually on the business side: finance for revenue, product for active customers. The data team writes the definition up and implements it, but should not be the one deciding what counts. The owner also approves future changes, so a jump in a chart can be traced to a decision rather than to a quietly edited filter.

Does anything I type leave my browser?

No. The builder makes no request, does not put anything in the page address, and stores nothing; reloading the page clears it. If analytics is enabled and you have consented, the only event sent is which button you used (copy, download Markdown, download CSV or print) on this tool, never the contents of the definition.

Does this write the SQL or the dbt model for me?

No, by design. The definition is the part that has to be agreed by people before anything is coded; once it is approved, it is the specification for the model, the semantic layer entry or the dashboard filter. It covers one metric at a time, without integrations or accounts.

From one written definition to numbers that agree

Service

Models and metrics that agree with each other.

Turning raw warehouse tables into a tested, documented modelling layer where every metric is defined once and every number can be traced to its source.

See what it covers

In-house · consumer marketplace platform

There was pressure to make the number match. The number was right.

Transactions were missing from reporting and the fastest fix would have massively over-counted revenue. Proving where the gap was mattered more than closing it fast.

Read it

These are from eight years owning the data warehouse and reporting function of a consumer marketplace platform, in-house rather than as an outside consultant. The employer and the internal system names are withheld; the numbers are the real ones.

The Divergence Point

Where the numbers stop agreeing, and what to do about it. One email a month on data quality, reconciliation and building warehouses that survive contact with a real business. No recycled LinkedIn posts.

Dashboards still disagree?

Writing the definition down is the first step. The analytics engineering engagement reconciles source, model and report, gets the business to choose, and codes each metric once, with tests.

Start a conversation