Mapping paywall views, checkout starts, trials, and purchases to standard events
Updated July 14, 2026 · 9 min read
Paid learning degrades when every monetization signal is collapsed into Purchase, or when Purchase is fired optimistically before payment is verified. A paywall funnel needs semantic separation: exposure, intent, trial, subscription, and paid revenue are different facts.
The right event taxonomy lets ad platforms optimize toward money while still giving you diagnostic visibility into where the funnel is leaking.
Recommended event boundary
- ViewContent: paywall or pricing surface became visible, including upgrade modals and locked feature prompts.
- InitiateCheckout: the user selected a plan or pressed a checkout/subscribe CTA that creates a billing intent.
- StartTrial: a free or paid trial entitlement started and is not yet recognized as paid revenue.
- Subscribe: a subscription relationship was created, when the platform semantics distinguish it from paid Purchase.
- Purchase: money was verified by Stripe, RevenueCat, Adapty, App Store, Play Billing, or your own backend.
A technical event contract
The contract should be identical across web, iOS, Android, and server workers. Producers may differ; semantics should not.
type MonetizationEvent =
| {
name: "ViewContent";
surface: "pricing_page" | "upgrade_modal" | "feature_gate" | "mobile_paywall";
content_category: "paywall";
}
| {
name: "InitiateCheckout";
plan_id: string;
checkout_id: string;
event_id: string;
}
| {
name: "StartTrial" | "Subscribe" | "Purchase";
transaction_id: string;
event_id: string;
value: number;
currency: string;
revenue_source: "stripe" | "revenuecat" | "adapty" | "app_store" | "play_billing";
};Where each event should fire
- 1Fire ViewContent on actual paywall visibility, not on page import or modal component mount before it is opened.
- 2Fire InitiateCheckout when a billing intent is created or a checkout session is requested, not on every hover or pricing-card impression.
- 3Fire StartTrial from the entitlement source that confirms trial activation, not from a button click that might fail payment method collection.
- 4Fire Purchase from the verified payment source of truth and deduplicate against any client-side Purchase.
- 5Keep renewals explicit. Either send recurring Purchase with the renewal value or separate lifecycle reporting, but do not overwrite original acquisition data with trial values.
Frequently asked questions
Should paywall viewed be a custom event?
Usually no. For Meta, ViewContent is the cleaner standard-event mapping for a paywall or pricing surface. Add content_category and surface metadata to distinguish pricing page, modal, and mobile paywall exposures.
Is StartTrial the same as Purchase?
No. A trial is an entitlement state, not verified revenue. Keep StartTrial and Purchase separate unless the trial is paid and the charged value is truly recognized at trial start.
Can web and mobile use the same funnel taxonomy?
Yes. The producers differ, but the semantics should be shared. Web might emit from Pixel, CAPI, and Stripe; mobile might emit from SDK, CAPI, RevenueCat, or Adapty. The event contract should stay consistent.
Related guides
Not sure which signal path is breaking?
Zoruko audits your web and mobile code for broken Meta and TikTok signal chains, then ships each fix as a pull request you review.
Run a free audit