The Core SaaS Event Model

Event tracking is the foundation of SaaS product analytics. Without a consistent, well-designed event model, every analysis question becomes a archaeology project: digging through inconsistent naming, missing properties, and events that were tracked for six months then changed and re-tracked differently. The cost of a bad event model is paid continuously — every time a data question cannot be answered cleanly, every time a dashboard is unreliable, every time a new analyst joins and cannot understand why the data looks the way it does.

This reference defines the canonical SaaS event model: the core event categories every SaaS should instrument, the naming conventions that keep the event taxonomy navigable at scale, and the property schemas that make events analytically useful across all categories.

🔑 The 6 Core Event Categories

A well-structured SaaS event model organizes all events into a small number of categories that correspond to distinct analytical use cases. The six categories below cover the full product lifecycle from user interaction to revenue.

These categories are not mutually exclusive — a single user action can trigger events in multiple categories. A user upgrading their plan generates a user event (upgrade action taken), an account event (account tier changed), and a billing event (subscription modified). Tracking these as separate events in their respective categories keeps each analytical question clean and avoids mixing concerns.

Event Naming Conventions

Consistent naming is what makes an event model navigable. Inconsistency accumulates quickly: one team names events user_signed_up, another uses UserSignedUp, another uses signup_completed. A few months in, you have four events that mean the same thing and no reliable way to query signup rates.

The Object-Action Pattern

The most widely adopted convention is the object-action pattern: [Object]_[Action] in snake_case. The object is the resource being acted on; the action is the past-tense verb describing what happened.

• → user_signed_up — not signup_completed or new_user_created
• → project_created — not create_project or new_project
• → subscription_upgraded — not upgrade_completed or plan_changed_up
• → report_exported — not export_report or download_initiated

Naming Rules

• → Always past tense for actions — events describe things that happened
• → snake_case throughout — no camelCase, no PascalCase, no spaces
• → Object first — this groups related events alphabetically in any tool
• → Be specific about the object — dashboard_widget_added not thing_added
• → No abbreviations unless universal — subscription not sub, organization not org

Event Name Registry

Maintain a central event registry — a document or database table — where every event name, its definition, who owns it, and when it was added is recorded. New events must be added to the registry before they are instrumented. This prevents duplicate events, enforces naming conventions, and gives analysts a source of truth.

Universal Property Schema

Every event in the model, regardless of category, should carry a set of universal properties. These are the context fields that make any event analytically useful: who did it, in what account, in what session, and when.

Category-Specific Property Schemas

In addition to universal properties, each event category has a set of standard properties that provide category-specific analytical context.

User Event Properties

• → user_role — the user's role in the account (admin, member, viewer)
• → user_plan — the subscription plan the user's account is on
• → user_created_at — the user's account creation date (for cohort analysis)
• → feature_context — which product area triggered this event

Account Event Properties

• → account_plan — current subscription plan
• → account_created_at — account creation date
• → account_size — number of seats or users in the account
• → previous_value / new_value — for state-change events (plan changes, seat count changes)

Billing Event Properties

• → plan_id — identifier of the subscription plan
• → amount — amount in cents (avoid floats for currency)
• → currency — ISO 4217 currency code
• → billing_period — monthly, annual
• → mrr_delta — MRR impact of this billing event

Error Event Properties

• → error_type — classification of the error (authentication, validation, integration, system)
• → error_code — application-specific error code
• → error_message — human-readable description (sanitized of PII)
• → severity — critical, high, medium, low
• → request_id — correlates the error to a specific API request

Example Event Taxonomy

The table below shows a representative event taxonomy for a B2B project management SaaS, illustrating how the naming convention and category structure apply in practice.

Common Instrumentation Mistakes

• → Tracking page views instead of actions. Page views tell you where users go. Action events tell you what they do. For product analytics, user and feature events are far more informative than page view counts.
• → Missing the anonymous-to-identified transition. Users interact with your product before signing up. Track anonymous events and alias them to the user ID at signup — otherwise you lose all pre-signup behavior context and cannot measure funnel conversion accurately.
• → Inconsistent property naming across events. user_id in one event and userId in another breaks any cross-event query. Enforce property naming consistency via a shared tracking plan and automated validation.
• → Tracking too many events too early. Instrumenting everything generates noise and maintenance burden. Start with the events that answer your most important product questions, then expand. A focused 30-event taxonomy is more useful than 300 poorly-defined events.
• → Not filtering test and internal users from analytics. Events from your team's accounts contaminate product metrics. Filter by email domain, user flag, or account property in your analytics pipeline to exclude internal usage.

Frequently Asked Questions