In this article
Start with a shared definition
An event contract is a short agreement about an event's meaning and expected data. It should be readable by the marketer who uses the report, the engineer who implements the event, and the operations team that recognizes the underlying order. Begin with the business rule that makes a purchase count.
Describe whether the event follows order creation, payment acceptance, or another agreed milestone. Name the authoritative system and identify who can change the definition. Without this agreement, two implementations can both run correctly while reporting different sets of orders.
Specify the values and their source
For each important field, record its name, meaning, type, source, and one example. State how the value is calculated and whether discounts, shipping, or taxes are represented separately. Map those decisions to each destination's current specification instead of assuming every platform uses identical terminology.
Google's GA4 ecommerce guidance says to provide event-level currency when sending value data. Its event reference also describes transaction_id as a unique transaction identifier that helps avoid duplicate purchase events. These platform requirements belong beside your business definitions, with clear ownership for the mapping.
Describe the awkward cases
A useful contract explains what happens when an order is retried, cancelled, partially refunded, or updated. It also says how test orders are identified and how multiple storefronts avoid ambiguous references. The goal is to make the expected behavior explicit before each case becomes a reporting question.
Include a small acceptance set with realistic examples. One simple order is helpful; a discounted order with several items is more revealing. Ask the reviewer to calculate the expected values from the source record before comparing them with the tracking payload.
- Definition: the business condition that creates the event.
- Fields: meaning, source, type, and realistic examples.
- Exceptions: retries, updates, refunds, and test activity.
- Ownership: implementation owner, reporting owner, and change process.
Version the agreement
When a definition changes, update the contract and record when the new behavior begins. Tell the people who compare periods or maintain downstream reports. A change from one revenue definition to another can look like performance movement unless the reporting team knows about it.
Keep the document close to the implementation notes and use it during reviews. Its value comes from repeated use: fewer assumptions during setup, clearer tests before release, and faster explanations when someone asks what the purchase number actually means.
