GuideAnalyticsEvent PropertiesTracking Plan

Event properties: what matters and how to construct them

All work

The short version

An event records that something happened. Its properties record everything you will later want to ask about it: which version the person saw, where they came from, what they chose, what they paid and why they stopped. Most product questions are answered by a property, and most misleading charts I have seen trace back to one that was missing, misspelled, mistyped or meant two things at once.

This is the companion to building click-funnel events you can trust, which covered the events themselves. It is properties, such as a version tag, that make a side-by-side test like the one in the onboarding case study possible at all. This guide covers what goes inside events, from naming and types to privacy and auditing, with a checklist at the end.

It is grounded in real work. I audited the production analytics project of a telehealth product I worked on: I inventoried every event property and checked how the important ones were actually populated, without pulling values for anything that looked like personal or health data. The project had grown the way most do, one feature and one quick fix at a time.

85%of event properties had no description at all
42%of funnel-entry events were missing the onboarding version tag
27groups of properties with the same name spelled two or three ways
4different meanings carried by one property called value

None of these broke anything loudly. They made some questions quietly unanswerable, or answerable two different ways. The examples below come from that audit, with the company unnamed and no volumes shown.

What a property is

An event needs a name, a timestamp and an identity. Properties are optional, and they are where the meaning lives. Mixpanel accepts any JSON value as a property: strings, numbers, booleans, lists and objects. In Mixpanel's format even the timestamp and identity travel inside the properties, as time and distinct_id. The browser SDK fills them in for you, along with a deduplication ID; on the server you send them yourself.

{
  "event": "Plan Selected",
  "properties": {
    "time": "2026-10-14T18:22:05Z",
    "distinct_id": "u_8f3a21",
    "plan_id": "monthly_basic",
    "price": 25.00,
    "currency": "USD",
    "onboarding_version": "v6",
    "platform": "web",
    "step_index": 4
  }
}

The event name is the verb; the properties are the rest of the sentence. Three facts shape everything below.

The kinds of property

"Property" covers several things that behave differently. Knowing which kind you are looking at explains most odd numbers.

The kinds of property (Mixpanel terms; other tools are similar)
KindDescribesHow it gets thereBehaviour to know
Event propertyThe momentSent with each eventCannot be edited once sent. Holds the state at the time.
User (profile) propertyThe person nowA separate profile callKeeps only the latest value, and every event joins to it.
Super propertyContext for every event from one deviceRegistered once in the client SDKStored on the device (a 365-day cookie by default in JavaScript). Never reaches server events on its own.
Group propertyAn account or companyA group profile, joined by a group keyPaid add-on. The key must be on the event, with no backfill.
Default propertyDevice, browser, location, URLCollected by the SDKMost names start with $ or mp_ (UTM parameters are the exception). Server events miss most.
Computed propertyA value derived at query timeCustom property or lookup tableWorks on historical data without code changes.

The point-in-time rule

A Mixpanel profile keeps only the latest value of each property, and every event joins to that value, not to what was true at the time. If a plan lives only on the profile and the person upgrades, all their old events look as if they happened on the new plan. So: anything that describes the moment goes on the event. Plan, price, version, step and platform at the time of the action are event properties; the profile is for who the person is now. If an idea lives in both places, name them differently, such as initial_utm_medium on the profile (Mixpanel's own first-touch name) and utm_medium on the event.

Building user properties

Profile properties are written with operations, and each operation suits a different kind of fact.

Super properties

register() sets a super property and overwrites any old value; register_once() only fills an empty one, which suits first-touch attribution. In the JavaScript SDK, a value passed directly to track() wins over a super property of the same name; other SDKs may differ, so avoid the collision. That SDK also keeps UTM parameters as super properties unless you set stop_utm_persistence: true, which Mixpanel recommends. And your server never sees super properties unless you pass them along.

The properties that matter most

A small core set of properties does most of the work in product decisions. These are the eight families I check first.

The core property set
FamilyTypical propertiesQuestion it answers
Identityuser ID, order IDWho did this?
Version and variantonboarding_versionDid the new version work?
Acquisitionutm_source, utm_mediumWhich channels convert?
Platformplatform, app_versionProduct problem or device problem?
Step and contextstep_name, entry_pointWhere, and what was on screen?
Moneyrevenue, currencyWhat is it worth?
Outcome and reasonerror_code, cancel_reasonWhy did it fail or stop?
Timingduration_ms, days_since_signupHow long, how soon?

1. Identity

Use an ID that is unique and never changes, such as a database ID; email fails the moment someone changes it. In Mixpanel's Simplified ID Merge (the default for organizations created since April 2024), the SDK generates an anonymous $device_id, identify() at signup or login sets $user_id, and reset() belongs at logout.

2. Version and experiment variant

This decides whether you can compare a new design with the old one, so it belongs on every event in the flow, from the first, under one name. In the audit, the onboarding version tag was on essentially every mid-funnel event but on only 58% of the entry event: the newer version had it every time, the older version was missing it on about three quarters. A sibling property agreed with it 100% of the time where both were set, which suggests timing: the older flow most likely attached the tag after its first event. Break that funnel down by the tag from its first step and about three quarters of old-version entrants land in (not set) instead of under their version. Switching attribution to First Step Defined hides the gap in funnels, but not in other reports.

3. Acquisition source

Campaign values are typed by people and pasted into links, so they rot. The audit found all the usual forms of decay:

Normalize at capture: lowercase, trim, map aliases, reject braces, and keep a documented list of allowed values. Tag test traffic. Keep first touch on the profile and last touch on each event.

4. Platform and app version

Browser and server events usually describe platform differently. In the audit, browser funnel events carried an operating system on every row (the page view on only about two thirds), while their server twins carried none, only a browser string from the forwarded user agent. A separate platform property held a real value on 13% of entry events and an empty string on 22%. No funnel could be split by operating system from end to end.

Send platform, app_version and a build number on every event, and forward them to the server. Give in-app browsers their own value: Facebook's accounted for 16 to 17% of account creations, and they handle cookies differently. Pass the client IP if you want server events located where the user is, not where your server is.

5. Step and context

step_name, step_index and entry_point say where something happened. What was on screen (how many options, which was preselected, where the chosen one sat) lets you test a design rather than count clicks. Send paths, not full URLs: query strings are where personal data hides. Mixpanel's JavaScript SDK sends $current_url, query string included, on every event by default, so strip the query in a before_send_events hook or drop the property with property_blacklist.

6. Money

Money properties have to add up, mean one thing and reconcile with the payment system. The audit found five ways they did not:

The rules that prevent all five:

7. Outcome, error and reason

8. Timing and durations

Naming properties

Mixpanel treats every spelling as its own property. Names are case-sensitive, so productNames and ProductNames are two properties (in the audit, both sat on the same checkout event), and orderId and order_id are two more. In the audit, 39% of event property names were camelCase, 14% snake_case, about a quarter single words, 12% Mixpanel's own $ properties, and the rest a mix, because the style followed the source system: the email and payment tools sent snake_case, the app camelCase. Vendors disagree on the convention (Mixpanel recommends snake_case for names and values; Amplitude defaults to Title Case), but all agree consistency matters most. My pick is snake_case for property names and values (the event names in this guide follow Segment's Title Case), because it survives warehouse SQL without quoting.

  1. Acronyms are words. order_id, not orderID or orderId. A clinician ID in the audit was split across three spellings, 77.5%, 21.6% and 0.8%, so analysis on one lost up to 22% of tagged events.
  2. Specific beats generic. payment_type, not type. The audit had type and Type, title and Title, user and User.
  3. Shape tells the type. Booleans as questions (is_returning), lists as plurals (product_ids), units in the name (duration_ms).
  4. No values in names. price with plan_id, not price_monthly_plan.
  5. Stay out of reserved space. No $ or mp in your own names. Never bucket, which makes other events disappear from the interface. $ignore makes Mixpanel silently drop the event. Do not shadow defaults: the audit had browser beside $browser and os beside $os.
  6. Translate vendor fields in the pipeline. Not in every report.
  7. Spell-check before you ship. Mixpanel cannot delete a property, so a typo lives on as a hidden ghost.

Types and formats

One property, one type, everywhere. Mixpanel's own guidance is that mixed types break queries and make charts unreliable.

Property types and their rules
TypeExampleRules
String, fixed values"monthly"Documented values, lower-case snake_case. Truncated past 255 bytes (accented characters take more than one).
Number20.00A JSON number, never text. No symbols. Unit in the name.
BooleantrueJSON true or false, always sent.
Date"2026-10-14T18:22:05"ISO 8601 in UTC; a string with no offset is read as UTC. Not epoch numbers or local time.
List["plan_basic", "addon_support"]A real JSON array. Fewer than 255 items, 8KB per event.
Object{"code": "welcome10"}Limited support: 3 levels deep, 8KB. Flat is almost always better.
ID"ord_10294"Always a string. For joining, not breakdowns.

Missing, null, empty and "undefined"

Mixpanel shows missing or null as (not set) and an empty string as (empty string). A literal "undefined" or "null" is the worst of both: in the audit, a filter for "undefined" matched rows where the property was simply missing, and "is set" counted empty strings as set. Leave a property out when it does not apply, and add an explicit unknown value when "we could not tell" is a real answer.

Booleans are the sharpest case, because Mixpanel reads "false", 0, null, empty and missing all as false. A sales-channel flag on server checkouts was missing on 48.7% of rows, false on 49.6% and true on 1.7%, so breakdowns showed "false" on about 98% of rows, when only 49.6% were actually false and 48.7% were unknown. And 24% of checkouts whose version string named that channel did not have the flag set to true: two sources for one fact, disagreeing.

Lists

On one payment event, product categories were JSON text inside a string on 100% of rows. The same basket in a different order counted as a different value (1.5% of rows), and related attributes sat in parallel lists that only lined up by position. Real arrays fix this: Mixpanel ignores list order and counts each item separately in breakdowns. For per-item detail, send a list of objects or one event per item.

Fixed values

The cleanest property in the audit was a two-letter region code: 100% populated and every value valid, probably because it came from a fixed list. The product name at checkout was the opposite: treatment, form and fulfilment partner in one string, double spaces in 5.4% of values, a "no decision" placeholder on 4.7%, and a different name for the same item on different events. Elsewhere, "N/A" filled 35% of one field. Send a stable product_id and look up the rest from one table.

Limits worth knowing

Mixpanel property limits (where the docs disagree, the safer figure)
LimitFigure
Properties per eventFewer than 255 (plan for 254)
String value255 bytes
Properties per user profileUp to 2,000
Distinct event properties per projectSoft limit of 5,000; beyond it, not indexed or offered in menus
Segments in a funnel or retention breakdown200, with the rest grouped as $other
Properties held constant in a funnel3
Unused properties leave menusAfter 28 days

Cardinality

Cardinality is how many distinct values a property takes. Platform has three or four; an order ID has one per order. Break down by low-cardinality properties, and keep IDs, timestamps, URLs and free text for joining, deduplication or nothing: funnel breakdowns show 200 segments and lump the rest into $other. Keep events lean, too. Amplitude suggests 20 properties or fewer per event, while Mixpanel's cap is about 255. The audit's browser checkout carried about 90 and its page view about 62. Wide events bury what matters, and every extra property is one more place personal data can slip in.

Where to set each property

Set each property where the truth is known, then forward it.

Where each property family should come from
FamilySource of truthHow it reaches other events
IdentityServer assigns the user ID; client holds the device IDidentify() at signup and login
Version and variantThe feature-flag or assignment serviceSuper property before the first event; sent with server requests
AcquisitionThe client, on landingKept on the device, sent to the server at signup
PlatformThe clientSuper property; sent with server requests
MoneyThe server or payment webhookNever computed in the browser
Outcome and reasonWhere the decision is madeOn the event that fires there

When the same event is tracked twice

About 18 events in the audit were tracked from both browser and server, under names that mostly differed only in style, and the copies disagreed. Browser copies counted 9 to 10% fewer people mid-funnel and 5% more at account creation. The newer onboarding version's share of new accounts on the two main versions was 40.6% on one copy and 45.1% on the other, so any version comparison depended on which copy it counted.

Some dashboard tiles had put a browser event and a server event in the same funnel, so the identities on the two copies did not line up. The team fixed three, and two still mixed them when the audit ended. The copies did have different names, but often only by casing, which is easy to miss in an event picker. A source property on nearly every event recorded which side each came from, and none of the dashboard's visible settings used it.

Keep one canonical copy per step: server for money and accounts, browser for interface events. If you keep both, tag the source and never mix copies in one funnel.

A shared tracking helper

Route every event through one function that knows the tracking plan. It normalizes values, drops unplanned and personal properties, and reports what is missing.

// Once, before the first event
mixpanel.register({
  onboarding_version: "v6",
  platform: "web",
  app_version: "4.12.0"
});

// Every event goes through this
export function track(event, props = {}) {
  const spec = plan[event];              // generated from the tracking plan
  if (!spec) return report("unplanned_event", event);

  const clean = {};
  for (const [key, value] of Object.entries(props)) {
    const rule = spec.properties[key];
    if (!rule) { report("unplanned_property", event, key); continue; }
    if (rule.personal) continue;         // never sent to analytics
    clean[key] = normalize(value, rule); // trim, lower-case, cast, check allowed values
  }
  for (const key of spec.required ?? []) {
    const missing = clean[key] === undefined
      && mixpanel.get_property(key) === undefined; // super properties count
    if (missing) report("missing_property", event, key);
  }
  mixpanel.track(event, clean);
}

Use the same plan on the server. The helper only sees the properties you pass, not the SDK's defaults such as $current_url, so in the browser Mixpanel's property_blacklist and before_send_events hook are a necessary second net. Tools such as Segment Protocols and Avo can also block or flag data that is not in the plan.

A property spec template

A well-formed server-side purchase event, in the shape Mixpanel's import API expects:

{
  "event": "Purchase Completed",
  "properties": {
    "time": "2026-10-14T18:22:05Z",
    "distinct_id": "u_8f3a21",
    "$insert_id": "9f2c71d04ab3e6f81c5d2a7b90e4f3c1",
    "order_id": "ord_10294",
    "plan_id": "monthly_basic",
    "product_ids": ["plan_basic", "addon_support"],
    "revenue": 20.00,
    "discount_amount": 5.00,
    "currency": "CAD",
    "coupon_code": "welcome5",
    "onboarding_version": "v6",
    "product_line": "core",
    "channel": "self_serve",
    "platform": "ios",
    "app_version": "4.12.0",
    "tracked_from": "server",
    "days_since_signup": 2,
    "is_test": false
  }
}

No name, email, address, card detail, free text or URL. Mixpanel's privacy guide says to record each property's definition, type, purpose and a personal-data flag. One row of a good tracking plan:

A tracking-plan row for the revenue property
FieldEntry
Namerevenue
DescriptionAmount charged for this order after discounts, excluding tax and shipping, in the currency given by currency
Type and formatNumber, two decimals, no symbol
Allowed valuesZero or greater (zero only for fully discounted orders). Refunds are a separate event.
Required onPurchase Completed, Subscription Renewed
Set fromServer, from the payment processor's confirmed charge
Question it answersRevenue per new account, by onboarding version and channel
OwnerA named product owner for the meaning, a named engineer for the code
Personal dataNone
HistoryReplaces the shared value on purchase events, with the date of change
CheckDaily total within 1% of the payment system

Privacy and health data

Personal data usually gets into analytics through properties, by accident: the easiest way to describe a form is to send the whole form. In a health product the product itself is sensitive. A treatment, a questionnaire answer or a condition-specific page can be health information once tied to a person.

In the audit, I classified every property name for personal and health information and did not pull values for anything flagged. It is quick, and it shows which events need a closer look. In health, start with onboarding and checkout.

Governance

85% of the audit's event properties and 80% of its user properties had no description, and every description on a raw tracked property was Mixpanel's automatic text. About a third of event names were hidden and a tenth were verified. That is what happens when nobody owns the schema.

How to audit your properties

This is the process I ran, in the order I would run it again. Most of it is a few hours of queries.

  1. Export the schema. Lexicon exports it to CSV. Normalize names (lower-case, no separators) to find collisions.
  2. Build a coverage grid. Each core property against each funnel event, using breakdowns rather than "is set". Anything under 100% needs a reason.
  3. Scan the values. Case variants, double spaces, braces, test values and placeholders.
  4. Check the types. Sum money properties and compare with the payment system.
  5. Read booleans raw. The true, false and missing split, not a breakdown.
  6. Compare the copies. People per step and variant mix, browser versus server.
  7. Count distinct values. Move anything near-unique out of breakdowns.
  8. Classify personal and health data. By name first, with compliance, and only then decide which values anyone needs to see.
  9. Map dependencies. Which reports use which properties.
  10. Use properties on anomalies. During the audit, one day's unique viewers reached more than four times the normal level, almost all of it in a few overnight hours. One property showed 85% of that traffic shared a single source value, and the bot flag marked none of it as automated. Isolating it took minutes.

Automated checks after every release

Releases break properties. Script these checks and run them in staging before each release and on production a day after.

Tag your own synthetic traffic. In the audit, a source value that looks like it came from a parity test had leaked into production. Send test runs to a separate project, or mark them is_test: true and filter them out everywhere.

What the audit found

Findings from one production analytics project, and the fix for each
FindingMeasureFix
Version tag missing at entry42% of entry events; about 74% for the older versionRegister before the first event
Copies disagreeVariant mix 40.6% versus 45.1%One canonical copy per step
One name, four meaningsCharges, cost, refunds and scores in valueSpecific names
Symbol in amounts100% of refund rows; sum of zeroNumbers plus a currency code
Several spellings27 collision groups; one ID split three waysOne convention, then merge
Unset booleans48.7% missing, reported as falseAlways send true or false
Catch-all values"N/A" in 35%; "no decision" in 4.7%IDs plus a lookup table
Platform splitOS absent on server copiesOne platform property everywhere

Not one of these showed up as an error; every chart rendered. That is what makes property problems expensive: they never look like problems, only like results.

The checklist

The takeaway

Events tell you that something happened. Properties decide whether you can ever learn why, for whom, and whether the change you shipped made a difference. They are cheap to get right on the day you add them and expensive forever after, because a tracked event cannot be edited, only deleted and re-sent. Give each property one name, one meaning and one type, set it where the truth lives, keep personal data out, and check it after every release. Then when a chart says the new version won, you can check it and trust what you find.

Work with us

Want a tracking plan you can trust?

I audit analytics projects, design property schemas and tracking plans, and set up the checks that keep them clean after every release.