Skip to content
Faisal Mahmud TusherDigital marketing, SEO & analytics
with Faisal Tusher

Marketing Data & Analytics Library › Measurement Templates

KPI Dictionary

A KPI dictionary template: name, definition, formula, grain, data source, owner, and direction and caveats for each metric.
Data resourceintermediate9 min readUpdated

What a KPI dictionary is for

A metric name is a label, and labels drift. "Conversion rate" can divide purchases by sessions, by users or by clicks; it can count every purchase event or only the first per session; it can use the analytics tool's count or the order system's. Each choice is defensible and each produces a different number, and without a dictionary the choice is made silently by whoever built each report. The dictionary makes the choice once, in writing, and gives it an owner. It is the human-readable face of a metrics layer, and the metrics layer guide explains how the same definitions are enforced in code; this page is the document that comes first, because a definition has to be agreed before it can be enforced.

The dictionary also serves the measurement plan. Every KPI the plan names should have a row here, and every row here should descend from a question in some plan, which is what keeps the dictionary from becoming a list of everything the tools can report. The KPI trees guide shows how metrics relate to one another arithmetically; the dictionary records the leaves and the branches of those trees with their definitions. For the general meaning of each metric, the glossary and the core metrics guide are the references; the dictionary is where a business pins the general meaning to its own data. It sits with the other two documents in the measurement templates hub.

The dictionary schema

Each metric is one row with the fields below. The fields are deliberately few; a dictionary that asks for twenty attributes per metric is never completed.

FieldWhat to writeWhy it is there
NameThe short name used in reports, exactly as it will appearReports and the dictionary must use the same string
DefinitionOne sentence in plain words stating what is counted and what is excludedThe sentence a non-analyst reads to know what the number means
FormulaNumerator and denominator, or the aggregation, in terms of named events or fieldsThe arithmetic a second analyst can reproduce
GrainThe unit the metric is computed at: session, user, order, click, day, campaignThe same formula at two grains gives two numbers
Data sourceThe system of record and the table or report the inputs come fromDecides which number is right when systems disagree
OwnerOne named person who approves changes to this rowDefinitions without owners drift
DirectionWhether higher is better, lower is better, or the metric is a guardrail with a rangePrevents "improvement" being read the wrong way
CaveatsKnown limits: consent gaps, modelled values, attribution window, lag before the number settlesThe context that stops the metric being over-read
Version and dateThe current version number and the date it changed, with a one-line noteA restated history can be explained

Direction deserves a note. Some metrics are inputs to be pushed, some are outputs to be watched and some are guardrails that must stay within a range; a cost metric that falls because tracking broke is not an improvement, and the caveat field is where that failure mode is recorded.

Starter entries

The table below is a starting set for a business that runs paid media and sells or generates leads online. Each row follows the schema with the formula written in terms of fields a typical analytics export or ad platform report provides. Adjust the sources to the systems in use and replace the placeholder owner roles with names. Formulas use the convention that "spend" means media cost excluding fees unless a business decides otherwise, and that decision belongs in the caveats column.

NameDefinitionFormulaGrainData sourceOwnerDirectionCaveats
SessionsVisits to the site as the analytics tool counts themCount of sessionsSessionAnalytics propertyAnalytics ownerContext, not a targetConsent gaps; bot filtering; session timeout rules
Click-through rate (CTR)Share of impressions that produced a clickClicks ÷ ImpressionsCampaign, adAd platform reportPaid media leadHigher is better, within reasonPlatform-specific definitions of a click; viewability not counted
Cost per clickMedia cost of one clickSpend ÷ ClicksCampaignAd platform reportPaid media leadLower is betterDepends on auction and targeting; not comparable across platforms
Cost per thousand impressionsMedia cost of a thousand impressionsSpend ÷ Impressions × 1,000CampaignAd platform reportPaid media leadLower is better for reach buysImpression definitions vary by platform and format
Conversion rate (CVR)Share of sessions that include a key eventSessions with the key event ÷ SessionsSessionAnalytics propertyAnalytics ownerHigher is betterGrain must match reports; a user grain gives a different value
Cost per acquisition (CPA)Media cost of one tracked conversionSpend ÷ ConversionsCampaign, channelAd platform spend; analytics conversionsPaid media leadLower is betterAttribution window and model; platform and analytics counts differ
Return on ad spend (ROAS)Revenue attributed to ads per unit of spendAttributed revenue ÷ SpendCampaign, channelOrder system revenue; ad platform spendPaid media leadHigher is betterReturns and cancellations; attribution window; revenue excludes tax and shipping
Average order valueRevenue per orderRevenue ÷ OrdersOrderOrder systemEcommerce leadHigher is usually betterDiscounts and returns; define whether shipping is included
Repeat purchase rateShare of customers with more than one order in the periodCustomers with a second order ÷ Customers with a first orderCustomerOrder systemRetention ownerHigher is betterPeriod length changes the value; define the window
Customer lifetime value (LTV)Margin a customer is expected to produce over a defined horizonAverage margin per order multiplied by expected orders in the horizonCustomer cohortOrder system; finance marginFinance partnerHigher is betterProjected, not observed; state the horizon and the model
Customer acquisition costSpend to acquire one new customerAcquisition spend ÷ New customersMonth, channelAd platform spend; order systemFinance partnerLower is betterWhich costs count as acquisition spend is a finance decision
Lead to opportunity rateShare of leads the sales team acceptedAccepted leads ÷ LeadsLeadCRMSales operationsHigher is betterLag between lead and acceptance; definition of "accepted"

The same starter set follows as plain CSV, with all nine schema fields, so that it can be pasted into a spreadsheet or a repository without the page's formatting. Replace the placeholder version and date with the real values, and the owner roles with names, before publishing it.

name,definition,formula,grain,data_source,owner,direction,caveats,version_and_date
Sessions,Visits to the site as the analytics tool counts them,Count of sessions,Session,Analytics property,Analytics owner,"Context, not a target",Consent gaps; bot filtering; session timeout rules,"1.0, YYYY-MM-DD, first entry"
Click-through rate (CTR),Share of impressions that produced a click,Clicks ÷ Impressions,"Campaign, ad",Ad platform report,Paid media lead,"Higher is better, within reason",Platform-specific definitions of a click; viewability not counted,"1.0, YYYY-MM-DD, first entry"
Cost per click,Media cost of one click,Spend ÷ Clicks,Campaign,Ad platform report,Paid media lead,Lower is better,Depends on auction and targeting; not comparable across platforms,"1.0, YYYY-MM-DD, first entry"
Cost per thousand impressions,Media cost of a thousand impressions,"Spend ÷ Impressions × 1,000",Campaign,Ad platform report,Paid media lead,Lower is better for reach buys,Impression definitions vary by platform and format,"1.0, YYYY-MM-DD, first entry"
Conversion rate (CVR),Share of sessions that include a key event,Sessions with the key event ÷ Sessions,Session,Analytics property,Analytics owner,Higher is better,Grain must match reports; a user grain gives a different value,"1.0, YYYY-MM-DD, first entry"
Cost per acquisition (CPA),Media cost of one tracked conversion,Spend ÷ Conversions,"Campaign, channel",Ad platform spend; analytics conversions,Paid media lead,Lower is better,Attribution window and model; platform and analytics counts differ,"1.0, YYYY-MM-DD, first entry"
Return on ad spend (ROAS),Revenue attributed to ads per unit of spend,Attributed revenue ÷ Spend,"Campaign, channel",Order system revenue; ad platform spend,Paid media lead,Higher is better,Returns and cancellations; attribution window; revenue excludes tax and shipping,"1.0, YYYY-MM-DD, first entry"
Average order value,Revenue per order,Revenue ÷ Orders,Order,Order system,Ecommerce lead,Higher is usually better,Discounts and returns; define whether shipping is included,"1.0, YYYY-MM-DD, first entry"
Repeat purchase rate,Share of customers with more than one order in the period,Customers with a second order ÷ Customers with a first order,Customer,Order system,Retention owner,Higher is better,Period length changes the value; define the window,"1.0, YYYY-MM-DD, first entry"
Customer lifetime value (LTV),Margin a customer is expected to produce over a defined horizon,Average margin per order multiplied by expected orders in the horizon,Customer cohort,Order system; finance margin,Finance partner,Higher is better,"Projected, not observed; state the horizon and the model","1.0, YYYY-MM-DD, first entry"
Customer acquisition cost,Spend to acquire one new customer,Acquisition spend ÷ New customers,"Month, channel",Ad platform spend; order system,Finance partner,Lower is better,Which costs count as acquisition spend is a finance decision,"1.0, YYYY-MM-DD, first entry"
Lead to opportunity rate,Share of leads the sales team accepted,Accepted leads ÷ Leads,Lead,CRM,Sales operations,Higher is better,"Lag between lead and acceptance; definition of ""accepted""","1.0, YYYY-MM-DD, first entry"

The rows are a vocabulary, not a verdict. A business that does not sell online removes the order rows; one that sells through a sales team adds pipeline rows. What matters is that every metric that appears on a dashboard or in a target has a row, and that the row says which system wins when numbers disagree.

Illustrative example — not a real result

Resolving a conversion rate dispute at an online tutoring service

An online tutoring service reports a "trial conversion rate" of 4.6 percent on the marketing dashboard and 3.1 percent in the monthly board pack. The marketing dashboard divides trial_started events by sessions in the analytics tool; the board pack divides trials recorded in the CRM by unique users from the same tool. Neither is wrong, but neither is defined. The analyst adds one row to the dictionary: trial conversion rate, defined as unique users who visit a pricing page and then start a trial, divided by unique users who visit a pricing page, computed at user grain. The visitor list comes from the analytics tool and the trial status from the CRM, which is the system of record for whether a trial started; the two are joined on the analytics user ID that the sign-up form stores on the CRM record, and only trials whose user ID is in the visitor list count in the numerator, so both sides describe the same people. CRM trials with no matching pricing-page visit, such as people who declined analytics cookies or signed up without visiting the page, are left out of the rate and reported as a separate unmatched count. The owner is the growth lead; the direction is higher is better; the caveats record the join key, the unmatched count and a two-day lag before CRM trials settle. Both reports are rebuilt from the row and show 3.4 percent, for instance 1,020 matched trial starters among 30,000 pricing-page visitors. The 1.5 point gap that had been discussed for two meetings disappears, and the difference between the old figures is recorded in the version note so that nobody re-opens it.

Governance

A dictionary is only trusted if it is stable, and only useful if it can change. The rules below balance the two. Every row has one owner, and only the owner approves a change; a request from anyone else is a proposal. Changes are versioned: the row's version increments, the date is set, and a one-line note says what changed and why, so that a chart which steps on the date of the change can be explained. Where a change restates history, the note says whether past reports were recalculated or left as they were, and the dashboard carries an annotation on the date. A metric that is retired stays in the dictionary with a retired status rather than being deleted, because old reports still reference it.

New rows arrive through the measurement plan: a KPI appears in a plan, the plan's owner proposes a row, and the dictionary owner checks that no existing row already covers it under another name. Reviews happen on a fixed cadence, monthly for a small team and quarterly for a stable one, and after any event that changes a source: a new analytics property, a CRM migration, a change to the order system's revenue definition. The review is simple: for each row, does the formula still match the dashboard, does the source still exist, and is the owner still in the role? The metrics layer guide describes how the same rows become code so that enforcement does not depend on people remembering the document; until that exists, the dictionary and a monthly reconciliation are the enforcement.

Common mistakes

  • Definitions without grain. The same formula at session and user grain gives different numbers; state the grain on every row.
  • No system of record. When analytics and the order system disagree, the row must say which wins; otherwise the dispute recurs monthly.
  • Owners who are teams. "Marketing" cannot approve a change; a person can.
  • Every available metric. A dictionary of everything the tools can export is never read. Rows exist because a plan asked a question.
  • Silent restatements. Changing a formula without a version note turns every historical chart into a mystery.
  • Direction left blank. A falling cost metric is read as good until someone notices tracking stopped; the direction and caveat fields are where that reading is corrected.
  • Treating the glossary as the dictionary. The glossary says what a metric generally means; the dictionary says what it means here, from which source, at which grain.

Terms used on this page

Frameworks

Where this page is used

Also related

Related