Three dashboards report ROAS, and all three show different values. One divides platform-attributed purchase value by media spend. Another uses store sales from the same calendar period. A third subtracts refunds and includes agency fees in the denominator. The disagreement is partly mathematical, not necessarily a tracking defect.
A metric dictionary makes these definitions explicit before a report, person, or AI operator uses them to make decisions. It can start as a short shared document. Its value comes from eliminating ambiguous substitutions, not from becoming a large catalog of every available field.
Begin with the metrics that trigger action
List the numbers used to increase budgets, pause campaigns, judge creative, or report client results. Prioritize these over decorative dashboard metrics.
For each one, ask what decision it supports. Cost per submitted lead may help diagnose form acquisition. Cost per qualified opportunity may support a different budget discussion. If the team uses one name for both, the automation cannot reliably infer the intended meaning.
Keep a separate entry for each materially different definition. Do not solve ambiguity by writing a long footnote that nobody sees when selecting the metric.
Use a complete definition record
| Field | What to write |
|---|---|
| Name | A human-readable label that identifies the outcome |
| Formula | Exact numerator and denominator |
| Source | Platform, report, table, or approved calculation |
| Time basis | Interaction date, event date, cohort date, or accounting period |
| Attribution | Model, window, and included interaction types where relevant |
| Units | Currency, percentage, count, or duration |
| Exclusions | Test records, cancellations, duplicates, and other filters |
| Freshness | Expected delay and when a result is mature enough to use |
| Owner | Person responsible for definition and implementation changes |
Include an example row that the team can calculate by hand. If nobody can reproduce a simple example, the definition is not ready to govern a consequential decision.
Write platform and business versions separately
An illustrative entry might define “Google Ads purchase ROAS” as selected purchase conversion value divided by cost in the same Google Ads reporting view. A separate entry could define “store revenue to media spend” using an order ledger and all included media channels.
Do not label both simply “ROAS” and rely on color to distinguish them. The MER and platform ROAS guide explains how these views can coexist in a budget review without being treated as interchangeable.
Google's conversion reporting reference is a source for understanding its report fields. Your dictionary should identify the field actually used rather than assuming a familiar label has the same meaning in every export.
Define edge cases before they appear
Specify what happens when the denominator is zero or missing. A campaign with no recorded purchases has an undefined purchase CPA under the usual spend-divided-by-purchases formula, not a zero-dollar CPA. A missing spend import is unknown spend, not free traffic.
Decide how to handle refunds, partially paid orders, repeat customers, duplicate leads, and reopened opportunities. Use the business's actual reporting policy and preserve the distinction between operational reporting and formal accounting.
For a percentage, name the denominator explicitly. “Conversion rate” could mean purchases per click, per session, per landing-page view, or per lead. Comparing those ratios under one label creates an error even when every underlying count is correct.
Make time and currency visible
Record the reporting timezone and the event date convention. A purchase late at night can fall on different days in different systems. Use the timezone reconciliation guide when reports disagree around day boundaries.
Currency deserves the same treatment. The currency reconciliation guide distinguishes source transaction currency, report currency, and finance's chosen conversion policy. Never add dollar amounts merely because the dashboard prints the same symbol beside them.
Google Analytics' currency reference illustrates why event currency and reporting currency can differ. Save both when they matter to the calculation.
Separate observed and estimated values
A projected lifetime value, expected pipeline value, and completed sale are different evidence types. Label modeled values in the metric name or adjacent metadata, and document the model's version and assumptions.
If an operator uses projected outcomes to make a budget recommendation, retain the observed values alongside them. The reviewer should be able to see whether the recommendation depends on an optimistic assumption.
Also define whether a recent period is preliminary. The same formula can produce a changing result while conversions arrive. A metric's freshness policy belongs in the dictionary because it changes how the number can be used.
Connect definitions to automation permissions
For each automated rule or agent instruction, identify the exact metric entry it uses. “Pause when CPA is high” is incomplete if the account has several CPA definitions.
Require the decision record to include the metric version, period, and source freshness. If the metric cannot be calculated under the documented definition, the operator should surface an unknown result instead of silently switching to an easier proxy.
This does not require a new analytics platform. A small mapping between the rule and a stable definition is enough to prevent many accidental substitutions.
Maintain the dictionary through changes
Version material changes rather than rewriting history invisibly. If the business begins subtracting refunds, document the effective date and whether historical reports are restated. If a conversion source changes, explain whether the old and new series remain comparable.
Review the dictionary when onboarding a client, introducing a new channel, changing a goal, or revising a dashboard. Retire unused entries so the document remains practical.
A good dictionary lets a new teammate reconstruct the number and understand the decision it supports. That shared understanding is the foundation for useful reporting and dependable advertising automation.