Event contract and measurement identity
8 min read
Lesson objectives
- Specify events, identifiers and reconciliation tests for paid-order measurement.
Please sign in to use all the tools
Once you sign in, the reading tools are yours: larger or smaller text, typeface, line spacing, focus mode, highlighting and bold, and notes saved to your account and gathered in My study.
Before building a growth dashboard, define the digital trace that a user action should produce. An event records an action at a time, such as beginning checkout or completing an order; it is neither proof of intent nor a guarantee that money was collected. An event contract is an agreement among product, analytics and finance teams about the event name, the instant it fires, the unit it represents, required parameters and how duplication is prevented. Its value appears when an interface or acquisition channel changes: the meaning of a purchase can remain stable instead of making a report compare two ways of recording an event. Start from a real journey: view an item, add it to a cart, start checkout, confirm payment and issue a refund. Recording every click under a generic name such as action destroys the ability to locate a break in the journey or choose a repair.
Give each event an implementation and test card. For purchase, specify that it fires after a transaction is confirmed rather than when the pay button is pressed, and include a stable transaction_id, value, currency and order status. Google Analytics ecommerce documentation describes purchase with transaction_id, value, currency and an items array, as well as a refund event when an order is refunded. That is a product-specific format; an organization may have a different internal system, but the business meaning must reconcile with it. If a browser sends purchase again whenever a customer revisits the thank-you page, one order may be counted twice. Use the order identifier as a reconciliation key, deduplicate in reporting when necessary and fix the repeated emission at its source.
Do not merge identities that you lack the right or ability to connect. A user_id assigned by an organization to a signed-in user differs from an anonymous device identifier, and both differ from an order transaction_id. A person may buy on a phone and later return on a laptop. User counts can therefore differ with identity method and consent. State whether a metric denominator is sessions, devices, accounts or unique customers in the order system. A similar email address or network address alone is not permission to join records. If a user declines a form of measurement, respect that choice and the applicable policy; missing observation is not an invitation to bypass it. This lesson designs honest measurement rather than declaring one legal rule for every country.
Separate essential from optional parameters. Essential fields let the team calculate and verify the outcome: event name, timestamp, order identifier for a purchase, currency alongside value, and confirmed transaction state in the finance source. Optional fields explain variation, such as plan or product category, provided they do not prompt unnecessary collection of personal data. Maintain a dictionary for parameter values. Does source mean the customer’s first source, the current session source or the campaign credited in attribution? One word can represent three different denominators. Assign responsibility for changing the contract and record a version. If active_customer is redefined, record when it changed and how the time series can be rebuilt. Versioning is a measurement control that makes a report reproducible, not learner-facing audit jargon.
Start verification from the most authoritative source for the outcome in question. For collected revenue, begin with captured transaction records and define how cancellations and refunds are treated. Compare analytics events by key, time and currency. Separate normal data arrival delay from actual loss: do not judge the last hour as though it were a closed month. Coverage rate is matched finance orders with an analytics event divided by eligible finance orders. Calculate it by browser, channel and day. If overall coverage is 97% while one channel has only 70%, channel acquisition-cost comparisons may be biased. Multiplying every channel by one overall correction factor does not solve uneven missingness.
A compact event contract might specify:
- event name purchase
- firing condition, the order reaches paid state in the payment server
- key, transaction_id
- value, collected order amount in the stated currency
- item_count, number of line items
- event time, payment confirmation rather than display of the success page
Test three cases. One successful payment yields one event with its stable key. A failed payment yields no purchase. Reloading the confirmation page yields no second event. If server emission is unavailable, the interface can send it with a deduplication design, but the team should test delivery reliability when selecting the emission point. Do not send a pre-discount cart value if finance records the collected post-discount amount; order counts may agree while values diverge. For a partial refund, record its amount and parent order so the full sale is not reversed by mistake.
For a weekly reconciliation, create columns named transaction_id, finance_status, finance_value, analytics_count, analytics_value and value_difference. A row with analytics_count=0 is an unobserved order; a count above one suggests duplication; a value difference calls for investigation of currency, discount or tax treatment. Deleting an anomalous row to improve coverage makes a neat report and a poorer decision. Start with the latest week whose data arrival period has ended, then segment the gaps by payment method and browser. If missingness clusters in a new payment method, withhold conclusions about the channel that uses it heavily until the flow is repaired. This tests the integrity of a data chain; it is not a claim that one analytics product prevents every loss.
Matching totals do not validate the journey sequence. If analytics reports 700 checkout starts and 650 purchases in one day, completion may appear high, but some purchases can belong to sessions started the previous day. Link permitted identifiers over a decision window or report daily event totals without inventing a funnel ratio. When consent prevents a stable identifier, do not fabricate a join between people. State the measurable scope, and test a purchase that completes the next day before accepting a conversion formula.
Lesson summary
Build an event contract and distinguish paid orders from analytics events.