Event Types

This page is the reference catalog of all events Apphud creates and sends to analytics and integrations. Each entry lists the event's UI name, its analytics name (the snake_case string used in CSV exports, integration payloads, and webhook bodies), when it fires, and any reasons or platform restrictions.

For the in-product Events page (filtering, integration delivery status, export), see Events. For event parameters (revenue, country, product fields, etc.), see Event Parameters and Properties.

Free trial events

Trial started

Fires when the user purchases a subscription with a free trial period.

Analytics name: trial_started.

Trial active

Fires if the trial is still active 1 hour after purchase. The 1-hour delay filters out short-lived trials that are quickly canceled.

Analytics name: trial_active.

📘

Adjusting the Trial active delay

For premium plan holders, the delay is configurable per-app in App settings → Customizations. Toggle the Trial Active switch and enter the desired delay in days, hours, and minutes (e.g., 0d 12h 0m for 12 hours, 3d 0h 0m for 72 hours, or any custom value).

When the switch is off, the default 1 hour applies. See Customizations for details.

Trial converted

Fires after the trial period ends and the user has been charged the regular subscription price for the first time.

Analytics name: trial_converted.

Trial canceled

Fires when auto-renew is turned off for any free-trial subscription. The current trial period may not yet be over.

Analytics name: trial_canceled.

Trial expired

Fires after the free trial period ends without conversion.

Analytics name: trial_expired.

Expiration reasons (iOS only):

Regular subscriptions

Events for subscriptions at the regular price (no trial, no intro, no promo).

Subscription started

Fires when a user purchases a subscription at the regular price.

Analytics name: subscription_started.

Subscription active

Fires if the paid subscription is still active 1 hour after purchase. Same logic as Trial active — filters out short-lived purchases that are quickly canceled.

Analytics name: subscription_active.

📘

Adjusting the Subscription active delay

For premium plan holders, the delay is configurable per-app in App settings → Customizations. Toggle the Subscription Active switch and enter the desired delay in days, hours, and minutes. When the switch is off, the default 1 hour applies. See Customizations.

Subscription renewed

Fires when the subscription renews and the user has been charged the regular price.

Analytics name: subscription_renewed.

Subscription canceled

Fires when auto-renew is turned off for any paid subscription.

Analytics name: subscription_canceled.

Subscription expired

Fires when the subscription period ends without renewal.

Analytics name: subscription_expired. Same expiration reasons as Trial expired.

Subscription refunded

Fires when the user has refunded the subscription.

Analytics name: subscription_refunded. Same refund reasons as Intro refunded.

Paid introductory offers

An introductory offer is a discount applied to new subscribers. See the blog post on iOS introductory offer types for background.

Intro started

Fires when the user purchases a subscription with an introductory offer.

Analytics name: intro_started.

Intro renewed

Fires when the subscription renews during the introductory offer.

Analytics name: intro_renewed.

Intro converted

Fires when the introductory offer ends and the user has been charged the regular subscription price for the first time.

Analytics name: intro_converted.

Intro expired

Fires when the subscription period ends without renewal during the intro offer.

Analytics name: intro_expired. Same expiration reasons as Trial expired.

Intro refunded

Fires when the user has refunded the subscription with an introductory offer.

Analytics name: intro_refunded.

Refund reasons (iOS only):

Promotional offers

iOS: purchases made using promotional offers. Android: purchases made using promo codes.

Promo started

Fires when the user activates a promotional offer (iOS) or a promo code (Android).

Analytics name: promo_started.

Promo renewed (iOS only)

Fires when a subscription renews during a promotional offer with a "pay as you go" type.

Analytics name: promo_renewed.

Promo converted

Fires when the promotional offer ends and the user has been charged the regular subscription price.

Analytics name: promo_converted.

Promo expired

Fires when the subscription lapses during a promotional offer.

Analytics name: promo_expired. Same expiration reasons as Trial expired.

Promo refunded (iOS only)

Fires when the user has refunded the subscription with a promotional offer through Apple Care support.

Analytics name: promo_refunded. Same refund reasons as Intro refunded.

Paywall events

Paywall shown

Fires when the paywall has been viewed by a user.

Analytics name: paywall_shown.

📘

Manual SDK call required

This event is sent manually via the paywallShown() SDK method. See Making Purchases.

Paywall closed (deprecated)

Fires when the user closes the paywall with a cross icon or any other cancellation link.

Analytics name: paywall_closed.

🚧

Deprecated

Sent manually via the paywallClosed() method. Deprecated starting from Apphud SDK v4.0.0.

Paywall checkout initiated

Fires when the user taps the selected product (or the Continue button) on the paywall and the system checkout popup appears.

Analytics name: paywall_checkout_initiated.

Paywall payment cancelled

Fires when the user cancels a purchase on the system checkout popup.

Analytics name: paywall_payment_cancelled.

Paywall payment error

Fires when the first purchase attempt from the paywall fails. The error originates from the native store payment flow (e.g., SKErrorDomain in StoreKit 1, StoreKitError in StoreKit 2, or Google Play Billing response codes). Stores do not always return a detailed error code, so the exact reason may be unavailable.

Analytics name: paywall_payment_error (available since 2026-Feb-16).

Other refund events (iOS only)

Apphud requires App Store Server Notifications v2 to be enabled to detect the refund-relevant events below.

Refund requested

Fires when a user requests a refund via Apple support for any in-app purchase (subscription or consumable). At this point Apple sends a CONSUMPTION_REQUESTED notification that Apphud processes to create the event.

Each transaction requested to be refunded has one corresponding event. Example: if a user subscribed weekly and requested refunds for the last month with 3 payments made during it, you'd see 3 Refund requested events.

Analytics name: refund_requested. No revenue is associated with this event.

Refund declined

Fires when Apple declines a user refund request. Without developer interference, this is rare.

To avoid refund abuse, developers can handle refund requests by analyzing user transaction history (Consumption data) and sharing it with Apple within the allowed timeframe. If Apple deems the request unfair after reviewing the consumption data, it declines the user's request and Apphud creates a Refund declined event.

Analytics name: refund_declined. No revenue is associated with this event.

📘

What happens when Apple approves a refund?

Whenever Apple approves a user's refund request (regardless of whether the developer submitted consumption data or not), Apphud generates a refund event corresponding to the purchase type of the request-associated transaction — Subscription refunded, Intro refunded, Promo refunded, or Non-renewing purchase refunded. All these events have negative revenue and therefore affect MRR.

Other events

Autorenew enabled (iOS only)

Fires when the subscription auto-renew is turned back on.

Analytics name: autorenew_enabled.

Autorenew disabled (deprecated, iOS only)

Fires when the subscription auto-renew is turned off. Includes both trial and paid subscriptions.

Analytics name: autorenew_disabled.

🚧

Deprecated

This event is marked for removal. Use Trial canceled and Subscription canceled instead.

Billing issue

Fires when subscription renewal fails because of a billing issue.

Analytics name: billing_issue.

Billing issue resolved

Fires when the subscription recovers from a billing issue.

Analytics name: billing_issue_resolved.

Non-renewing purchase

Fires when a user purchases a non-renewable product (consumable or non-consumable).

Analytics name: non_renewing_purchase.

Non-renewing purchase refunded

Fires when the user has refunded a non-renewable product.

Analytics name: non_renewing_purchase_refunded.

User created

Fires when the user is created in Apphud.

Analytics name (when enabled): user_created.

🚧

Not created by default

Enable this event in integration settings or Server-to-Server webhooks before it starts appearing.

Not included in CSV exports.

Revenue

Duplicates all revenue events (including refunds) under the single revenue name.

🚧

Integrations only — use with caution

Intended for use in Integrations when necessary. Does not affect Apphud analytics and is not included in CSV exports.

Enable only if you fully understand the implications and the risk of revenue duplication on the destination side.

App reinstalled

Fires when the SDK detects a reinstall.

Analytics name: app_reinstalled. See Reinstalls tracking for details.

Subscription changed (iOS only)

Fires whenever a product of a subscription changes.

Analytics name: subscription_changed.

When events are created

Apphud regularly sends requests to App Store and Google Play to update subscription state and to create new events as needed. This means events can appear with a delay after the store-side change (typically minutes, but can be longer for state changes that depend on server notifications).

For real-time delivery to integrations, see Server-to-Server Webhooks and Server Notifications.

FAQ

What's the difference between subscription_started and subscription_active?

subscription_started fires immediately on purchase. subscription_active fires 1 hour later if the subscription is still active — it filters out impulse purchases that get refunded within the hour. Use subscription_active for retention-style metrics and subscription_started for raw acquisition.

Same as above for trials — trial_started vs trial_active?

Same logic. trial_started is the raw count; trial_active is the 1-hour-later count (configurable to 12 / 72 hours / custom on higher plans). Use trial_active to exclude immediately-canceled trials.

Which events affect MRR?

All revenue-bearing events: subscription_renewed, subscription_started, intro_started, intro_renewed, promo_started, promo_renewed, non_renewing_purchase, plus their refunded counterparts (with negative revenue). The standalone refund_requested and refund_declined events carry no revenue and do not affect MRR.

Which events are iOS only?

promo_renewed, promo_refunded, refund_requested, refund_declined, autorenew_enabled, autorenew_disabled (deprecated), and subscription_changed.

Why does my Events page show an event but my integration didn't receive it?

Most likely the integration is configured to skip that event type, or the destination returned an error. Open the event row in Events → Event details modal to see per-connection status and the error message.

How do I disable specific events from being sent to an integration?

In the integration's connection settings, toggle off the events you don't want. See Integrations Overview for the events selector.