Definition
A commerce metric contract is an explicit, versioned specification of a business measure. It states the calculation, unit of analysis, source events, filters, time basis, currency treatment, freshness expectation, and owner. It is an analytics agreement rather than a legal contract, and its purpose is to make a number reproducible and interpretable.
Why It Matters
- Two dashboards can both say return rate while one counts orders with any return and the other counts returned units. The disagreement is semantic even if both queries run correctly.
- Agents acting on an undefined margin or revenue measure may apply a threshold to a number that excludes relevant costs or includes immature orders.
- A Commerce Intelligence OS requires shared definitions across reporting, predictive features, and action rules so a change in meaning is visible.
How It Works
- Name the metric and define its grain, numerator, denominator, exclusions, event clock, and permitted dimensions. Include an example with a hand-calculated expected result.
- Map every input to authoritative sources and state treatment of cancellations, partial returns, missing values, and currency conversion where applicable.
- Assign an owner and version the definition. Record effective dates and decide whether a change restates history or creates a new series.
- Validate a small reference dataset across consumers. Display the metric version and data cutoff in decision evidence, and investigate mismatches before changing operational thresholds.
Ecommerce Example
Context: Illustrative example: 100 orders contain 200 units. Ten orders each return one unit.
Recommended move: The order-level rate is 10%, while the unit-level rate is 5%. Give the measures different names and contracts rather than choosing whichever number looks better.
Why it matters: Both calculations can be correct for their definitions. The operating decision must use the measure its threshold was designed for.
iKawn Framework
Specify
In the iKawn framework, attach metric definitions to commerce entities and events.
Validate
Use reference cases to make calculation differences visible.
Version
Preserve the meaning and effective period of each measure.
Apply
Connect agent rules and commercial reviews to the correct contract and cutoff.
Concise Summary
A metric contract makes commercial meaning explicit. Formula, grain, timing, and change ownership help dashboards and agents act on comparable numbers.