---
title: "Well-known events"
description: "The typed event catalog — standard event names that carry validated schemas and richer dashboards."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.pug.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Well-known events

Well-known events are the predefined event names Pug recognizes, with typed
property schemas enforced at ingestion. The catalog holds **127 events across 19
families**, listed in full below.

Every SDK type-checks them, but the call shape differs:

| SDK | Call | Available |
|-----|------|-----------|
| **Flutter** | `Pug.track.purchase(productId: …, amount: …)` — a generated method per event | all 127 |
| **Web** | `track('purchase', { productId, amount })` — the name narrows the property type | 119 (events flagged for other platforms are excluded) |
| **Node** | `pug.track(distinctId, 'purchase', { … })` | 114 |
| **HTTP** | `kind: "purchase"` with wrapped `customProperties` | all 127 |

Either way the check is at compile time, so an unknown property or a wrong type
is an error before the event leaves the device.

Custom event names (any snake\_case string other than a `pug.`-prefixed kind) are accepted without schema validation. See [Events API](/api/events) for the `pug.` prefix restriction and validation error format.

**Further reading:** [Tracking events](/sdks#track-events) — sending custom and well-known events from each SDK

## Commerce

Product browsing, cart, checkout, and purchase events. `price` is a single-item price; `amount` is a transaction total. `currency` is an uppercase ISO 4217 code (e.g. `USD`, `EUR`). Money fields use the major currency unit (e.g. dollars, not cents).

| Event | Properties | Description |
|---|---|---|
| `product_viewed` | `product_id`\* string, `product_name` string, `category` string, `brand` string, `sku` string, `price` double, `currency` string | User viewed a product detail page |
| `product_list_viewed` | `list_id`\* string, `list_name` string, `category` string, `item_count` int | User viewed a product listing, category, or search-results page |
| `add_to_cart` | `product_id`\* string, `price` double, `currency` string, `cart_id` string, `quantity` int, `category` string, `brand` string, `sku` string | Item added to cart |
| `remove_from_cart` | `product_id`\* string, `price` double, `currency` string, `cart_id` string, `quantity` int, `category` string, `brand` string, `sku` string | Item removed from cart |
| `cart_viewed` | `cart_id` string, `item_count` int, `amount` double, `currency` string | User opened the cart |
| `wishlist_added` | `product_id`\* string, `wishlist_id` string, `price` double, `currency` string | Item added to wishlist |
| `wishlist_removed` | `product_id`\* string, `wishlist_id` string | Item removed from wishlist |
| `coupon_applied` | `coupon_id`\* string, `coupon_code` string, `cart_id` string, `discount_amount` double, `currency` string | Coupon applied to cart |
| `coupon_removed` | `coupon_id`\* string, `coupon_code` string, `cart_id` string, `reason` string | Coupon removed from cart |
| `checkout_started` | `product_id` string, `amount` double, `currency` string, `cart_id` string, `checkout_id` string, `item_count` int | User initiated checkout |
| `checkout_step_completed` | `checkout_id`\* string, `step`\* string, `step_index` int | A checkout step was completed |
| `purchase` | `product_id` string, `amount` double, `currency` string, `order_id` string, `quantity` int, `category` string, `brand` string, `sku` string | Order completed (fires once per successful order after payment is confirmed) |
| `order_refunded` | `order_id`\* string, `amount` double, `currency` string, `reason` string | Order was refunded |

## Authentication

Sign-up, sign-in, sign-out, email verification, password reset, and MFA lifecycle. All auth events have no required properties beyond the event kind; common method values are `"email"`, `"google"`, `"github"`, `"totp"`, `"sms"`, `"webauthn"`, `"backup_codes"`.

| Event | Properties | Description |
|---|---|---|
| `signup` | — | User completed registration |
| `signin` | — | User signed in |
| `signout` | — | User signed out |
| `email_verified` | — | Email address was verified |
| `password_reset_requested` | — | Password reset was requested |
| `password_reset_completed` | — | Password reset flow completed |
| `mfa_enabled` | `method` string | MFA was enabled |
| `mfa_disabled` | `method` string | MFA was disabled |

## App Lifecycle

Native mobile lifecycle events from the Flutter SDK (iOS and Android) — the Web SDK does not emit these. The SDK auto-emits only `app_open` and `app_close` (plus `screen_view` for navigation); the rest are typed events you track manually.

| Event | Properties | Description |
|---|---|---|
| `app_open` | — | App launched or brought to the foreground |
| `app_close` | — | App moved to the background or closed |
| `app_install` | `app_version` string, `install_source` string | First launch after a fresh install |
| `app_update` | `app_version`\* string, `previous_version` string | First launch after an app update |
| `app_backgrounded` | — | App moved to the background |
| `app_foregrounded` | — | App returned to the foreground |
| `app_crashed` | `error_message` string, `error_type` string | Unhandled crash (also available on desktop) |
| `screen_view` | `screen_name`\* string, `screen_class` string | A native screen was viewed — the mobile equivalent of `page_view` |

## App Usage

Cross-platform — available in every SDK.

| Event | Properties | Description |
|---|---|---|
| `feature_used` | `feature_id`\* string, `feature_name` string | A named feature was used |

## Billing

Subscription, invoice, payment, trial, and refund lifecycle. `currency` is an uppercase ISO 4217 code; `amount` is the transaction total in the major currency unit.

| Event | Properties | Description |
|---|---|---|
| `subscription_started` | `subscription_id`\* string, `plan_id` string, `amount` double, `currency` string | New subscription was created |
| `subscription_changed` | `subscription_id`\* string, `previous_plan_id` string, `new_plan_id` string | Subscription plan was changed |
| `subscription_canceled` | `subscription_id`\* string, `plan_id` string, `reason` string | Subscription was canceled |
| `subscription_renewed` | `subscription_id`\* string, `plan_id` string, `amount` double, `currency` string | Subscription renewed |
| `subscription_paused` | `subscription_id`\* string, `plan_id` string, `reason` string | Subscription was paused |
| `subscription_resumed` | `subscription_id`\* string, `plan_id` string, `reason` string | Paused subscription was resumed |
| `subscription_trial_will_end` | `subscription_id`\* string, `plan_id` string, `trial_id` string | Trial is nearing expiry (fires in advance, e.g. 3 days before) |
| `trial_started` | `trial_id` string, `plan_id` string | Free trial started |
| `trial_converted` | `trial_id` string, `subscription_id` string, `plan_id` string | Trial converted to paid subscription |
| `invoice_paid` | `invoice_id`\* string, `subscription_id` string, `amount` double, `currency` string | Invoice was paid |
| `invoice_failed` | `invoice_id`\* string, `subscription_id` string, `amount` double, `currency` string, `reason` string | Invoice payment failed |
| `payment_succeeded` | `payment_id` string, `invoice_id` string, `subscription_id` string, `amount` double, `currency` string | Payment succeeded |
| `payment_failed` | `payment_id` string, `invoice_id` string, `subscription_id` string, `amount` double, `currency` string, `reason` string | Payment failed |
| `payment_method_added` | `payment_method_id` string, `payment_method_type` string | Payment method was added |
| `payment_method_removed` | `payment_method_id` string, `payment_method_type` string | Payment method was removed |
| `refund_failed` | `order_id`\* string, `refund_id` string, `amount` double, `currency` string, `reason` string | Refund attempt failed |

## Chat

Conversation lifecycle, message delivery, membership, calls, attachments, and reactions. `conversation_id` is the durable chat identifier. `member_id` is the conversation-membership ID, not the SDK `distinct_id`. Common values: `conversation_type` — `"dm"`, `"group"`, `"channel"`, `"broadcast"`; `message_type` — `"text"`, `"image"`, `"video"`, `"audio"`, `"file"`, `"system"`. `duration`-typed props (e.g. `mute_duration`) serialize as `{ "seconds": N, "nanos": N }` — see [Notes](#notes).

| Event | Properties | Description |
|---|---|---|
| `chat_created` | `conversation_id`\* string, `conversation_type` string, `participant_count` int | Conversation was created |
| `chat_joined` | `conversation_id`\* string, `conversation_type` string | User joined a conversation |
| `chat_left` | `conversation_id`\* string, `conversation_type` string, `reason` string | User left a conversation |
| `chat_deleted` | `conversation_id`\* string, `conversation_type` string, `reason` string | Conversation was deleted |
| `chat_archived` | `conversation_id`\* string, `conversation_type` string | Conversation was archived |
| `chat_unarchived` | `conversation_id`\* string, `conversation_type` string | Conversation was unarchived |
| `chat_member_added` | `conversation_id`\* string, `member_id`\* string, `role` string | Member was added to a conversation |
| `chat_member_removed` | `conversation_id`\* string, `member_id`\* string, `reason` string | Member was removed from a conversation |
| `chat_member_role_changed` | `conversation_id`\* string, `member_id`\* string, `previous_role` string, `new_role`\* string | Member's role was changed |
| `chat_member_muted` | `conversation_id`\* string, `member_id`\* string, `mute_duration` duration | Member was muted (duration omitted for indefinite mutes) |
| `chat_user_blocked` | `user_id`\* string | User was blocked (not conversation-scoped) |
| `chat_message_sent` | `conversation_id`\* string, `message_id` string, `conversation_type` string, `message_type` string, `character_count` int, `attachment_count` int, `thread_id` string, `parent_message_id` string | Message was sent |
| `chat_message_received` | `conversation_id`\* string, `message_id` string, `conversation_type` string, `message_type` string, `character_count` int, `attachment_count` int, `thread_id` string, `parent_message_id` string | Message was received |
| `chat_message_failed` | `conversation_id`\* string, `message_id` string, `conversation_type` string, `reason`\* string, `thread_id` string | Message send failed |
| `chat_message_read` | `conversation_id`\* string, `message_id` string, `conversation_type` string, `thread_id` string | Message was read |
| `chat_message_deleted` | `conversation_id`\* string, `message_id` string, `conversation_type` string, `reason` string, `thread_id` string | Message was deleted |
| `chat_message_edited` | `conversation_id`\* string, `message_id` string, `conversation_type` string, `thread_id` string | Message was edited |
| `chat_message_pinned` | `conversation_id`\* string, `message_id` string, `conversation_type` string, `thread_id` string | Message was pinned |
| `chat_message_unpinned` | `conversation_id`\* string, `message_id` string, `conversation_type` string, `thread_id` string | Message was unpinned |
| `chat_typing_started` | `conversation_id`\* string, `conversation_type` string | User started typing (typer is the SDK `distinct_id`) |
| `chat_typing_stopped` | `conversation_id`\* string, `conversation_type` string | User stopped typing |
| `chat_attachment_uploaded` | `conversation_id`\* string, `message_id` string, `attachment_id`\* string, `attachment_type` string, `size_bytes` int64, `thread_id` string | Attachment uploaded in chat |
| `chat_attachment_downloaded` | `conversation_id`\* string, `message_id` string, `attachment_id`\* string, `attachment_type` string, `size_bytes` int64, `thread_id` string | Attachment downloaded from chat |
| `chat_call_started` | `conversation_id`\* string, `call_id`\* string, `call_type` string | Call was started |
| `chat_call_joined` | `conversation_id`\* string, `call_id`\* string, `call_type` string | User joined a call |
| `chat_call_left` | `conversation_id`\* string, `call_id`\* string, `call_type` string, `duration` duration | User left a call |
| `chat_call_screen_shared` | `conversation_id`\* string, `call_id`\* string | Screen sharing started on a call |
| `chat_call_recording_started` | `conversation_id`\* string, `call_id`\* string | Call recording started |
| `chat_reaction_added` | `conversation_id`\* string, `message_id` string, `reaction`\* string, `thread_id` string | Reaction added to a message |
| `chat_reaction_removed` | `conversation_id`\* string, `message_id` string, `reaction`\* string, `thread_id` string | Reaction removed from a message |

## Discovery / Search

Search queries, results, recommendations, filters, and sorting. These events capture how users explore and find content.

| Event | Properties | Description |
|---|---|---|
| `search` | `query`\* string | Search query submitted |
| `search_result_clicked` | `query`\* string, `result_id`\* string, `index` int | User clicked a search result |
| `recommendation_viewed` | `recommendation_id`\* string, `item_id` string, `source` string, `index` int | Recommendation impression |
| `recommendation_clicked` | `recommendation_id`\* string, `item_id`\* string, `source` string, `index` int | User clicked a recommendation |
| `filter_applied` | `key`\* string, `value` string | Filter was applied |
| `sort_changed` | `key`\* string, `direction` string | Sort order was changed |

## Error

Application errors and exceptions. `(PII)` marks fields handled under the project's scrubbing and data-residency rules (see [Notes](#notes)).

| Event | Properties | Description |
|---|---|---|
| `error_occurred` | `error_code`\* string, `message` string (PII), `severity` string, `unhandled` bool, `stack` string (PII) | An error was caught or escaped to a global handler. Common `severity` values: `"info"`, `"warning"`, `"error"`, `"fatal"`. Set `unhandled: true` when the error escaped application code |

## File

File upload, download, and export events.

| Event | Properties | Description |
|---|---|---|
| `file_uploaded` | `file_id`\* string, `file_name` string (PII), `file_type` string, `size_bytes` int64 | File was uploaded |
| `file_downloaded` | `file_id`\* string, `file_name` string (PII), `file_type` string, `size_bytes` int64 | File was downloaded |
| `export_started` | `export_id`\* string, `export_type` string | Data export was initiated |
| `export_completed` | `export_id`\* string, `export_type` string, `size_bytes` int64 | Data export completed |

## Form

Form interaction start and submission.

| Event | Properties | Description |
|---|---|---|
| `form_start` | `form_id`\* string, `form_name` string | User began filling in a form |
| `form_submit` | `form_id`\* string, `form_name` string, `action` string | Form was submitted |

## Integration

Third-party integration connect and disconnect. Common `integration_type` values: `"slack"`, `"github"`, `"linear"`, `"salesforce"`, `"hubspot"`, `"zapier"`, `"webhook"`.

| Event | Properties | Description |
|---|---|---|
| `integration_connected` | `integration_id` string, `integration_type`\* string | Integration was connected |
| `integration_disconnected` | `integration_id` string, `integration_type`\* string, `reason` string | Integration was disconnected |

## Invitation

Workspace invitation sent and accepted.

| Event | Properties | Description |
|---|---|---|
| `invite_sent` | `invite_id` string, `workspace_id` string, `inviter_id` string, `invitee_id` string, `invitee_email` string (PII), `role` string | Invitation was sent |
| `invite_accepted` | `invite_id` string, `workspace_id` string, `inviter_id` string, `invitee_id` string, `invitee_email` string (PII), `role` string | Invitation was accepted |

## Media

Video and audio playback events. `video_started` / `audio_started` fire on first play of a session; `video_play` / `audio_play` fire on resume from pause. `position`, `from_position`, and `to_position` are durations from the start of the media.

| Event | Properties | Description |
|---|---|---|
| `video_started` | `video_id`\* string | Video playback started for the first time in this session |
| `video_play` | `video_id`\* string, `position` duration | Video resumed from pause |
| `video_pause` | `video_id`\* string, `position` duration | Video was paused |
| `video_seeked` | `video_id`\* string, `from_position` duration, `to_position` duration | User seeked in video |
| `video_completed` | `video_id`\* string | Video playback reached the end |
| `audio_started` | `audio_id`\* string | Audio playback started for the first time in this session |
| `audio_play` | `audio_id`\* string, `position` duration | Audio resumed from pause |
| `audio_pause` | `audio_id`\* string, `position` duration | Audio was paused |
| `audio_seeked` | `audio_id`\* string, `from_position` duration, `to_position` duration | User seeked in audio |
| `audio_completed` | `audio_id`\* string | Audio playback reached the end |

## Navigation

Page views, clicks, scroll depth, and frustration signals. Page URL, title, referrer, and UTM parameters are provided as [auto-properties](/reference/auto-properties) (`$url`, `$pageTitle`, `$referrer`, `$utmSource`/`$utmMedium`/`$utmCampaign`/…) on every event — they do not appear as typed properties here.

| Event | Properties | Description |
|---|---|---|
| `page_view` | — | Web page navigation or SPA route change (auto-tracked by Web SDK) |
| `click` | `class` string, `id` string, `tag` string, `text` string, `x` int, `y` int | Element click — Web only |
| `rage_click` | `click_count` int (≥2), `element` string, `x` int, `y` int | Multiple rapid clicks on the same non-responsive target — Web only |
| `dead_click` | `element` string, `text` string, `x` int, `y` int | Click with no observable response — Web only |
| `scroll` | `percent` int (0–100), `scroll_y` int | Scroll depth milestone — Web and mobile |

## Notification

Notification receipt, click, and dismissal. `notification_type` describes the delivery channel: `"push"`, `"email"`, `"in_app"`, `"sms"`.

| Event | Properties | Description |
|---|---|---|
| `notification_received` | `campaign_id`\* string, `notification_type` string | Notification was received by the client |
| `notification_clicked` | `campaign_id`\* string, `notification_type` string | User clicked a notification |
| `notification_dismissed` | `campaign_id`\* string, `notification_type` string | User dismissed a notification |

## Social

| Event | Properties | Description |
|---|---|---|
| `share` | — | User shared content |

## Support

Feedback, NPS, surveys, support tickets, live chat, and help articles.

| Event | Properties | Description |
|---|---|---|
| `feedback_submitted` | `feedback_id` string, `category` string, `comment` string (PII) | Feedback was submitted |
| `nps_submitted` | `score` int (0–10), `comment` string (PII) | NPS score was submitted |
| `survey_started` | `survey_id`\* string | Survey was started |
| `survey_completed` | `survey_id`\* string, `question_count` int | Survey was completed |
| `support_ticket_created` | `ticket_id`\* string, `category` string, `priority` string | Support ticket was opened |
| `support_ticket_resolved` | `ticket_id`\* string, `resolution` string (PII) | Support ticket was resolved |
| `support_chat_started` | `conversation_id`\* string, `topic` string (PII) | Support chat session started |
| `help_article_viewed` | `article_id`\* string, `article_title` string, `category` string | Help article was viewed |

## Workspace

Workspace creation, membership, role changes, and settings.

| Event | Properties | Description |
|---|---|---|
| `workspace_created` | `workspace_id`\* string, `workspace_name` string | Workspace was created |
| `workspace_joined` | `workspace_id`\* string, `role` string | User joined a workspace |
| `workspace_deleted` | `workspace_id`\* string, `reason` string | Workspace was deleted |
| `workspace_role_changed` | `workspace_id`\* string, `member_id`\* string, `previous_role` string, `new_role`\* string | Member's workspace role was changed |
| `workspace_settings_updated` | `workspace_id`\* string, `setting`\* string | A workspace setting was changed |

## API

API key management events.

| Event | Properties | Description |
|---|---|---|
| `api_key_created` | `api_key_id` string, `name` string, `scope` string | API key was created |
| `api_key_revoked` | `api_key_id` string, `name` string, `reason` string | API key was revoked |

## Notes

**Required props** are marked with \* — the API returns `invalid_argument` if a required property is missing or the wrong type. Optional props may be omitted.

**PII-tagged props** are labelled `(PII)` above. Fields tagged PII in the schema are subject to the project's data-residency and scrubbing rules.

**`duration` type** — duration properties (e.g. `position`, `mute_duration`, `duration`) are serialized as a JSON object `{ "seconds": N, "nanos": N }`.

**`pug.` prefix is reserved** — custom event kind strings must not start with `pug.`. The API rejects any custom event whose `kind` begins with that prefix. See [Events API](/api/events).

**Web vs Flutter** — the Web SDK exposes all events listed here except the mobile app lifecycle events (`app_open`, `app_close`, `app_install`, `app_update`, `app_backgrounded`, `app_foregrounded`, `app_crashed`, `screen_view`). The Flutter SDK includes those and drops the DOM-interaction events (`click`, `rage_click`, `dead_click`). Its navigation event is `screen_view` on mobile; on **web** targets Flutter emits `page_view` instead.

Source: https://docs.pug.sh/reference/well-known-events/index.mdx