Subscriptions

AppFunnel tracks the full subscription lifecycle via Stripe webhooks. When a subscription is created, renewed, canceled, or changes status, AppFunnel updates internal records and emits events to your configured integrations.

Subscription Statuses

Status	Description
`ACTIVE`	Subscription is current and paid.
`TRIALING`	Subscription is in a free or paid trial period. No recurring charge yet.
`PAST_DUE`	Payment failed on renewal. Stripe will retry according to your retry settings.
`CANCELED`	Subscription has been fully canceled. No further charges will occur.
`CANCELLING`	Subscription is scheduled to cancel at the end of the current period. Still active until `cancelAt` date.
`UNPAID`	All payment retry attempts have been exhausted. Subscription is suspended.
`INCOMPLETE`	Initial payment failed or requires additional action.
`INCOMPLETE_EXPIRED`	Initial payment was not completed within the allowed time window.

Status Transitions


                    TRIALING
                       |
                       v
INCOMPLETE -----> ACTIVE <-----> PAST_DUE
                    |                |
                    v                v
              CANCELLING          UNPAID
                    |
                    v
                CANCELED

The most common lifecycle:

Direct purchase: ACTIVE from day one. Renews automatically.
Free trial: TRIALING —> ACTIVE when the trial ends and the first charge succeeds.
Paid trial: TRIALING (one-time trial fee charged separately) —> ACTIVE when the subscription’s first recurring charge succeeds.
Cancellation: ACTIVE —> CANCELLING (if cancel-at-end-of-period) —> CANCELED.
Failed renewal: ACTIVE —> PAST_DUE —> either back to ACTIVE (retry succeeds) or UNPAID / CANCELED (all retries exhausted).

Webhook Events

AppFunnel listens to the following Stripe webhook events for subscription management:

Stripe Event	What AppFunnel Does
`customer.subscription.created`	Creates a subscription record. Sets status and period dates.
`customer.subscription.updated`	Updates status, period dates, cancellation schedule. Detects trial-to-active conversion.
`customer.subscription.deleted`	Marks subscription as `CANCELED`. Records cancellation timestamp.
`invoice.paid`	Records the renewal payment. Updates subscription period. Emits `subscription.renewal` event for integrations.
`invoice.payment_failed`	Updates subscription to `PAST_DUE`. Emits failure notification for integrations.
`charge.refunded`	Records the refund against the original payment event.

Webhook events are deduplicated by Stripe event ID. If a webhook is delivered multiple times (retries), only the first delivery is processed.

Acquisition Types

Each subscription records how it was acquired:

Type	Description
`direct`	No trial. First charge happens immediately at checkout.
`free_trial`	Free trial period. Card is captured via SetupIntent, first charge happens when the trial ends.
`paid_trial`	Paid trial. A one-time trial fee is charged at checkout, then the subscription enters a trial period before the first recurring charge.

The acquisition type is stored in the subscription metadata and is available in analytics for segmentation.

Trial-to-Active Conversion

When a subscription transitions from TRIALING to ACTIVE, AppFunnel:

Updates the subscription status.
Records the first recurring payment (from the invoice.paid webhook).
Emits a subscription.renewal integration event with the payment amount.

This transition is tracked automatically — no configuration needed. The conversion appears in your analytics and flows through to all configured integrations (Meta CAPI, Customer.io, webhooks, etc.).

Revenue Events

Payment events feed into analytics and integrations at each stage of the subscription lifecycle:

Event	When	Integration Event Type
Initial purchase	Checkout completed	`purchase.complete`
First purchase ever	Customer’s very first payment	`customer.first_purchase`
Subscription created	After checkout or trial start	`subscription.created`
Renewal payment	Each successful recurring invoice	`subscription.renewal`
Payment failed	Failed renewal attempt	— (logged, no integration event)
Refund	Charge refunded in Stripe	— (recorded internally)

These events are emitted to all configured integrations. For example:

Meta CAPI receives Purchase events for renewals, enabling LTV-based ad optimization.
Customer.io receives subscription status updates for triggering email workflows (e.g., “Your trial is ending soon”).
Webhooks receive all events for custom backend processing.
RevenueCat syncs subscription data for cross-platform analytics.

See Integrations for configuration details.

Viewing Subscriptions

Subscription records are visible in the AppFunnel dashboard:

Customer detail page — Shows all subscriptions for a customer, with status, period dates, and acquisition type.
Analytics — Revenue metrics (MRR, ARPU, subscription conversion rate) are computed from subscription and payment event data.

AppFunnel tracks subscriptions but does not manage them (no cancel/upgrade/downgrade UI for end users). Subscription management should be handled through Stripe’s Customer Portal or your own backend. AppFunnel reflects the current state via webhooks.