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

# Event taxonomy

> The lifecycle events FloKit uses for payback analysis, cohort quality, and recommendations.

FloKit uses lifecycle events to join acquisition spend to subscription outcomes. You can send events via the [Events API](/api-reference/events), [RevenueCat or Adapty webhooks](/integrations/revenuecat), or your data warehouse. The more complete your event coverage, the richer FloKit's payback analysis.

***

### user\_created

**When to send:** User account is created or on the first app open.

| Field            | Required    | Notes                                 |
| ---------------- | ----------- | ------------------------------------- |
| `user_id`        | Required    | Your backend user identifier          |
| `timestamp`      | Required    | ISO 8601                              |
| `anonymous_id`   | Recommended | Pre-login device/session ID           |
| `platform`       | Recommended | `ios`, `android`, `web`               |
| `country`        | Recommended | ISO 3166-1 alpha-2                    |
| `install_source` | Recommended | e.g. `app_store`, `play_store`, `web` |

**Why FloKit uses it:** Anchors the user identity graph and establishes the first touchpoint for the LTV window. All downstream events are measured relative to this timestamp.

***

### install\_attributed

**When to send:** Send from your MMP (AppsFlyer, Adjust) or server-side when attribution resolves — typically within seconds to minutes of install.

| Field                       | Required    | Notes                                          |
| --------------------------- | ----------- | ---------------------------------------------- |
| `user_id` or `anonymous_id` | Required    | At least one must be present                   |
| `timestamp`                 | Required    | Attribution timestamp, ISO 8601                |
| `campaign_id`               | Required    | Campaign identifier from the ad platform       |
| `channel`                   | Required    | e.g. `meta`, `google_ads`, `tiktok`, `organic` |
| `ad_set_id`                 | Recommended | Ad set / ad group identifier                   |
| `creative_id`               | Recommended | Creative-level identifier                      |
| `country`                   | Recommended | ISO 3166-1 alpha-2                             |
| `keyword`                   | Recommended | Search keyword if applicable                   |
| `attribution_model`         | Recommended | e.g. `last_click`, `view_through`              |

**Why FloKit uses it:** The critical join point between ad spend and downstream subscription outcomes. Without this event, CAC and payback calculations cannot be attributed to a campaign.

***

### onboarding\_started

**When to send:** User enters the onboarding flow.

| Field       | Required    | Notes                                     |
| ----------- | ----------- | ----------------------------------------- |
| `user_id`   | Required    |                                           |
| `timestamp` | Required    | ISO 8601                                  |
| `variant`   | Recommended | A/B test variant identifier if applicable |

**Why FloKit uses it:** Measures the top of the onboarding funnel. Combined with `onboarding_completed`, FloKit computes completion rates per cohort and acquisition source.

***

### onboarding\_completed

**When to send:** User finishes the onboarding flow.

| Field             | Required    | Notes                                |
| ----------------- | ----------- | ------------------------------------ |
| `user_id`         | Required    |                                      |
| `timestamp`       | Required    | ISO 8601                             |
| `steps_completed` | Recommended | Number of onboarding steps completed |
| `variant`         | Recommended | A/B test variant identifier          |

**Why FloKit uses it:** Onboarding completion rate is a leading indicator of trial and subscription intent. FloKit surfaces completion-rate deltas across acquisition channels and creative cohorts.

***

### paywall\_viewed

**When to send:** A paywall screen is displayed to the user.

| Field        | Required    | Notes                                                                           |
| ------------ | ----------- | ------------------------------------------------------------------------------- |
| `user_id`    | Required    |                                                                                 |
| `timestamp`  | Required    | ISO 8601                                                                        |
| `paywall_id` | Required    | Identifier for the paywall variant                                              |
| `offer_id`   | Recommended | Promotional offer shown, if any                                                 |
| `plan_ids`   | Recommended | Array of plan identifiers shown on the paywall                                  |
| `variant`    | Recommended | A/B test variant                                                                |
| `context`    | Recommended | Where in the app the paywall appeared, e.g. `onboarding_step_3`, `feature_gate` |

**Why FloKit uses it:** Measures paywall impression-to-trial conversion. Essential for offer and pricing analysis — FloKit tracks which paywalls, offers, and contexts drive the highest-quality subscribers.

***

### trial\_started

**When to send:** User starts a free trial.

| Field               | Required    | Notes                              |
| ------------------- | ----------- | ---------------------------------- |
| `user_id`           | Required    |                                    |
| `timestamp`         | Required    | ISO 8601                           |
| `plan_id`           | Required    | Identifier for the plan            |
| `trial_length_days` | Required    | Length of the trial period in days |
| `offer_id`          | Recommended | Offer applied, if any              |
| `paywall_id`        | Recommended | Paywall that converted this user   |
| `transaction_id`    | Recommended | Platform transaction identifier    |
| `price`             | Recommended | `0` for free trials                |

**Why FloKit uses it:** Trial start is the primary subscription intent signal. Trial-to-paid conversion rate is FloKit's core payback metric — the quality of a cohort is largely determined by how its trials convert.

***

### subscription\_started

**When to send:** User completes their first paid purchase.

| Field             | Required    | Notes                                        |
| ----------------- | ----------- | -------------------------------------------- |
| `user_id`         | Required    |                                              |
| `timestamp`       | Required    | ISO 8601                                     |
| `plan_id`         | Required    |                                              |
| `revenue`         | Required    | Net revenue in the specified currency        |
| `currency`        | Required    | ISO 4217, e.g. `USD`                         |
| `transaction_id`  | Required    | Deduplicates revenue events                  |
| `offer_id`        | Recommended |                                              |
| `paywall_id`      | Recommended |                                              |
| `trial_converted` | Recommended | `true` if this subscription followed a trial |
| `store`           | Recommended | `apple`, `google`, `stripe`                  |

**Why FloKit uses it:** First revenue event used for CAC payback calculation. FloKit joins this event to `install_attributed` to compute time-to-first-revenue and return on ad spend.

***

### renewal\_completed

**When to send:** A subscription renews at each billing cycle.

| Field            | Required    | Notes                                 |
| ---------------- | ----------- | ------------------------------------- |
| `user_id`        | Required    |                                       |
| `timestamp`      | Required    | ISO 8601                              |
| `plan_id`        | Required    |                                       |
| `revenue`        | Required    |                                       |
| `currency`       | Required    | ISO 4217                              |
| `transaction_id` | Required    | Unique per renewal                    |
| `renewal_count`  | Recommended | Number of renewals including this one |
| `store`          | Recommended | `apple`, `google`, `stripe`           |

**Why FloKit uses it:** The renewal sequence builds the LTV curve. FloKit uses renewal cadence to project payback windows and flag cohorts with declining retention.

***

### subscription\_cancelled

**When to send:** User cancels their subscription. Note: the user may remain active until the current billing period ends — cancellation does not mean immediate churn.

| Field                 | Required    | Notes                                      |
| --------------------- | ----------- | ------------------------------------------ |
| `user_id`             | Required    |                                            |
| `timestamp`           | Required    | ISO 8601 — when cancellation was requested |
| `plan_id`             | Required    |                                            |
| `cancellation_reason` | Recommended | Reason from the platform or user-reported  |
| `store`               | Recommended | `apple`, `google`, `stripe`                |

**Why FloKit uses it:** Flags cohorts with elevated cancellation intent. Combined with renewal data, FloKit distinguishes between early cancellations (poor quality signal) and cancellations after multiple renewals (healthy LTV).

***

### refund\_issued

**When to send:** A refund is processed.

| Field                     | Required    | Notes                                        |
| ------------------------- | ----------- | -------------------------------------------- |
| `user_id`                 | Required    |                                              |
| `timestamp`               | Required    | ISO 8601                                     |
| `amount`                  | Required    | Refunded amount                              |
| `currency`                | Required    | ISO 4217                                     |
| `transaction_id`          | Required    | Unique identifier for the refund transaction |
| `reason`                  | Recommended | Refund reason                                |
| `store`                   | Recommended | `apple`, `google`, `stripe`                  |
| `original_transaction_id` | Recommended | References the original purchase             |

**Why FloKit uses it:** Removes revenue from payback calculations. Cohorts with high refund rates are flagged as low-quality acquisition — a signal that creative or targeting is attracting non-intent users.

***

### plan\_changed

**When to send:** User upgrades or downgrades their subscription plan.

| Field          | Required    | Notes                         |
| -------------- | ----------- | ----------------------------- |
| `user_id`      | Required    |                               |
| `timestamp`    | Required    | ISO 8601                      |
| `from_plan_id` | Required    | Previous plan                 |
| `to_plan_id`   | Required    | New plan                      |
| `new_revenue`  | Required    | Revenue at the new plan price |
| `currency`     | Required    | ISO 4217                      |
| `direction`    | Recommended | `upgrade` or `downgrade`      |

**Why FloKit uses it:** Plan changes affect LTV and payback trajectory. Upgrade rate from a cohort is a positive signal; high downgrade rates suggest pricing misalignment.

***

### offer\_viewed

**When to send:** A promotional offer is displayed to the user.

| Field          | Required    | Notes                                      |
| -------------- | ----------- | ------------------------------------------ |
| `user_id`      | Required    |                                            |
| `timestamp`    | Required    | ISO 8601                                   |
| `offer_id`     | Required    |                                            |
| `paywall_id`   | Recommended |                                            |
| `discount_pct` | Recommended | Discount percentage, e.g. `50` for 50% off |

**Why FloKit uses it:** Measures offer impression-to-redemption rate. FloKit surfaces which offers drive incremental subscriptions vs. which discount existing intent.

***

### checkout\_started

**When to send:** User begins the checkout process (enters payment details or taps to subscribe).

| Field        | Required    | Notes    |
| ------------ | ----------- | -------- |
| `user_id`    | Required    |          |
| `timestamp`  | Required    | ISO 8601 |
| `plan_id`    | Required    |          |
| `offer_id`   | Recommended |          |
| `paywall_id` | Recommended |          |

**Why FloKit uses it:** Checkout abandonment rate surfaces pricing friction. A high `checkout_started` to `checkout_completed` drop-off signals a problem with the checkout UX, pricing, or payment method coverage.

***

### checkout\_completed

**When to send:** Purchase completes. Use alongside or instead of `subscription_started` for web flows where checkout and subscription creation are distinct steps.

| Field            | Required    | Notes                            |
| ---------------- | ----------- | -------------------------------- |
| `user_id`        | Required    |                                  |
| `timestamp`      | Required    | ISO 8601                         |
| `plan_id`        | Required    |                                  |
| `revenue`        | Required    |                                  |
| `currency`       | Required    | ISO 4217                         |
| `transaction_id` | Required    |                                  |
| `offer_id`       | Recommended |                                  |
| `store`          | Recommended | Typically `stripe` for web flows |

**Why FloKit uses it:** Confirms the revenue event for web subscription flows. For Stripe-based subscriptions where RevenueCat is not used, this is the primary first-revenue signal.

***

### campaign\_touch

**When to send:** User is exposed to a campaign — an ad impression or click.

| Field                       | Required    | Notes                               |
| --------------------------- | ----------- | ----------------------------------- |
| `user_id` or `anonymous_id` | Required    | At least one must be present        |
| `timestamp`                 | Required    | ISO 8601                            |
| `campaign_id`               | Required    |                                     |
| `channel`                   | Required    | e.g. `meta`, `google_ads`, `tiktok` |
| `creative_id`               | Recommended |                                     |
| `ad_set_id`                 | Recommended |                                     |
| `touch_type`                | Recommended | `impression` or `click`             |

**Why FloKit uses it:** Builds multi-touch attribution models and creative fatigue signals. High impression frequency with declining click-through rate flags creative exhaustion.

***

### creative\_seen

**When to send:** A specific creative (video, image, or copy variant) is viewed.

| Field                       | Required    | Notes                             |
| --------------------------- | ----------- | --------------------------------- |
| `user_id` or `anonymous_id` | Required    | At least one must be present      |
| `timestamp`                 | Required    | ISO 8601                          |
| `creative_id`               | Required    |                                   |
| `campaign_id`               | Required    |                                   |
| `view_duration_ms`          | Recommended | How long the creative was in view |
| `platform`                  | Recommended | `ios`, `android`, `web`           |

**Why FloKit uses it:** Creative fatigue and retained-value-per-creative analysis. FloKit correlates creative exposure sequences with downstream subscription quality to surface which creatives attract high-LTV users.