> For the complete documentation index, see [llms.txt](https://docs.neonblue.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neonblue.ai/data/event-model.md).

# Event Model: Positive, Negative, and Flow-Specific Goals

#### 1. Purpose of this page

This page explains how Neon Blue uses events to:

* Measure what is working or not working in experiments
* Train optimization models
* Define clear success and failure criteria for each flow

It is intended for data, analytics, and lifecycle teams configuring Neon Blue for the first time or expanding it to new flows.

***

#### 2. How Neon Blue uses events

Neon Blue optimizes experiences such as:

* Email flows (welcome, abandoned cart, replenishment, subscription reminders)
* On-site experiences (banners, hero modules, content blocks)

To optimize these experiences, the platform needs to know:

* When something desirable happens (a positive event)
* When something undesirable happens (a negative event)

These events are logged in an event stream (typically exposed in Snowflake) and used to define:

* Optimization metrics for the machine learning models
* Reporting metrics for measurement and dashboards

***

#### 3. Event schema assumptions

Neon Blue expects a general-purpose events table, for example:

`neon_blue_inbound.events`

with at least:

* `user_id` – canonical user identifier
* `event_name` – e.g. `email_click`, `email_unsubscribe`, `order_placed`, `subscription_cancelled`
* `occurred_at` – timestamp (UTC)
* `source` – system where the event originated (ESP, ecommerce, analytics, backend)
* `properties` – JSON/VARIANT with additional context (flow name, template id, subscription id, etc.)

Optional fields that are often useful:

* `event_type` – high-level label such as `positive`, `negative`, `neutral`
* `value` – numeric value associated with the event (optional, often unused initially)

Neon Blue reads this table as a continuous event stream and defines metrics over this stream.

***

#### 4. Positive events

Positive events represent outcomes Neon Blue is trying to increase.

At the optimization level, these are usually:

* Upper-funnel or mid-funnel actions that occur frequently enough to provide learning signal
* Clearly attributable to the flow or surface being optimized

Common examples:

* Email or on-site engagement
  * `email_click`
  * `onsite_cta_click`
* Early funnel actions
  * `started_checkout`
  * `viewed_key_page` (for high-intent pages)
* Subscription or account actions
  * `subscription_kept`
  * `subscription_addon_added`

Guidelines for choosing positive events:

* Choose events that occur at a reasonable rate so the model can learn quickly.
* Prefer events that are tightly related to the experience being optimized (for example, clicks on that flow’s emails, not any click in the account’s history).
* Use downstream conversion or revenue events for reporting, not necessarily as the primary optimization signal.

It is common for the primary optimization positive event for email flows to be “did the user click any email in this flow within a configured window.”

***

#### 5. Negative events (guardrails)

Negative events represent outcomes Neon Blue is trying to avoid. These are used as guardrails so optimization does not chase short-term gains at the expense of long-term health.

Common negative events:

* Messaging-level negatives
  * `email_unsubscribe`
  * `spam_complaint`
* Business-level negatives
  * `subscription_cancelled`
  * `plan_downgrade`
  * `account_closed`

Negative events can be treated in two ways:

1. As explicit negative terms in the optimization metric (for example, click rate minus a penalty for unsubscribe rate).
2. As business rules for state updates (for example, if a user orders and later cancels, treat that user as if the order never contributed value in long-term reporting).

For initial configurations, it is usually sufficient to designate:

* A small set of unsub/complaint events as universal guardrails
* Flow-specific business negatives (such as cancellations) where relevant

***

#### 6. Flow-specific goals

Each flow or surface area is configured with its own goal definition. This combines:

* A selected positive event (or metric constructed from one or more events)
* Selected negative events that act as guardrails
* Optional reporting metrics that are measured but not used for optimization

A useful mental model:

* Define a global “metric dictionary” (for example, “clicked within 3 days”, “ordered within 7 days”, “unsubscribed within 7 days”).
* For each flow, select the metric to optimize and the supporting metrics to report.

**6.1 Example: Welcome flow**

* Optimization goal
  * Positive: `email_click` on any welcome email within 3 days of first welcome send
  * Negative: `email_unsubscribe` within 7 days of first welcome send
* Reporting metrics
  * `first_order_placed` within 14 days of entering the welcome gate
  * Revenue per user in 30 days after entering the welcome gate

**6.2 Example: Abandoned cart flow**

* Optimization goal
  * Positive: `order_placed` within 3 days of abandoned cart email
  * Negative: `email_unsubscribe` within 7 days
* Reporting metrics
  * Revenue per user in 7 and 14 days after abandoned cart email
  * Recovery rate (percentage of abandoned carts converted)

**6.3 Example: Subscription reminder flow**

* Optimization goal
  * Positive: `subscription_kept` or `subscription_addon_added` within a configured window
  * Negative: `subscription_cancelled`, `plan_downgrade`, plus email unsubscribes
* Reporting metrics
  * Net revenue from subscription orders in 30 days after reminder
  * Cancellation rate per gate entry

***

#### 7. Binary vs value-based events

Events can be used either as:

* Binary signals (the event happened or did not happen), or
* Value signals (the event includes a numeric `value` field such as revenue or cost)

Neon Blue is designed to operate with **binary events only** for optimization:

* A click is treated as “1” if it occurred, “0” otherwise.
* An unsubscribe is treated as “1 negative event” if it occurred, “0” otherwise.

Value-based optimization (for example, optimizing directly for revenue per variant) is possible but typically requires:

* Higher event volumes
* Stable and agreed-upon value definitions (for example, how to value long-tail repeat purchases or subscription revenue)

For most lifecycle programs, the recommended progression is:

1. Start with binary events and clear reporting on orders and revenue.
2. Once test volume and data quality are high enough, consider value-based metrics where appropriate.

***

#### 8. Configuration pattern

In practice, configuration usually follows this pattern:

1. Define a small set of standardized event-based metrics, for example:
   * `clicked_within_3d`
   * `unsub_within_7d`
   * `ordered_within_7d`
   * `subscription_cancelled_within_14d`
2. For each flow or surface, configure:
   * `optimization_metric`: one of the positive metrics (with optional negative terms)
   * `reporting_metrics`: one or more downstream metrics used for analysis
3. Maintain this configuration in a shared location (for example, a YAML file, a configuration table, or the Neon Blue console), so there is a single source of truth.

***

#### 9. FAQ

**Does every flow need the same goal event?**\
No. Different flows can and should use different goal events if their objectives are different. For example, a welcome flow may target engagement, while an abandoned cart flow may target conversion.

**Do events need a numeric value?**\
No. Binary presence/absence is sufficient for Neon Blue’s optimization models. Values are optional and can be layered in later for value-based optimization if needed.

**How many positive and negative events should be configured per flow?**\
Most flows work best with one primary positive event and a small number of negative events. Additional reporting metrics can be tracked without being part of the optimization formula.

**Where do revenue and LTV show up?**\
Orders and revenue are handled through the `orders` table and are mainly used for reporting and business impact measurement, rather than as the direct optimization target. See the Attribution & Windows page for more details.