# RevenueCat

Join app behavior with purchases, trials, renewals and churn. Submetry's client events and RevenueCat webhook share the RevenueCat app user ID.

## Import apps with OAuth

In [Setup](https://submetry.com/app/setup), choose Importer RevenueCat and connect your account. Select the apps to import. Submetry creates or links matching projects; each has its own App ID and ingestion key. Existing imports are idempotent, and removed apps can be restored through re-import.

OAuth discovers projects and apps. It does not modify your application, enable a webhook automatically or backfill previous purchases. Complete both code instrumentation and webhook configuration below.

## Link user identity

Configure RevenueCat before your Submetry adapter. Use the current RevenueCat app user ID, even before account login:

| Framework | RevenueCat identity |
| --- | --- |
| Native Swift | `Purchases.shared.appUserID` |
| Native Android | `Purchases.sharedInstance.appUserID` |
| Flutter | `await Purchases.appUserID` |
| React Native / Expo | `await Purchases.getAppUserID()` |

Pass it as `userId` in Swift configure or `uid` in HTTP events. After successful identity changes, call `Submetry.identify` or update the adapter's user ID. Keep the existing RevenueCat purchase implementation.

## Configure the webhook

Open Setup for that app or Dashboard → Integrations. Generate the RevenueCat webhook Authorization secret. Copy it immediately: only its hash is stored and it cannot be read back. Regeneration invalidates the previous secret.

In RevenueCat → Project → Integrations → Webhooks, create an app-specific webhook:

| Field | Value |
| --- | --- |
| URL | The Submetry URL shown for this app: `https://api.submetry.com/v1/integrations/revenuecat?app_id=YOUR_APP_ID` |
| Authorization header | The exact `Bearer …` value generated by Submetry |
| App scope | The corresponding RevenueCat store app |
| Events | All relevant subscription lifecycle events |
| Environment | Production for live revenue; sandbox for development verification |

Submetry currently authenticates this webhook using the configured Bearer secret. Do not use the `sub_pk_` SDK key or a private `sub_sk_` analytics key for webhook authentication. For an imported app, the RevenueCat event app ID must match the linked app.

## Event normalization

| RevenueCat event | Submetry event / effect |
| --- | --- |
| INITIAL_PURCHASE with TRIAL period | `rc_trial_started`; no paid revenue |
| INITIAL_PURCHASE with paid period | `rc_initial_purchase` |
| RENEWAL with trial conversion | `rc_trial_converted` |
| RENEWAL otherwise | `rc_renewal` |
| CANCELLATION | `rc_cancellation`; cancellation differs from expiration |
| EXPIRATION | `rc_expiration` |
| NON_RENEWING_PURCHASE | `rc_non_renewing_purchase` |
| Other lifecycle types | `rc_` plus the lowercase type |
| TEST | Connectivity status only; no purchase/event row generated |

RevenueCat's event ID deduplicates retries. Sandbox events are stored in the `sandbox` environment. Revenue uses USD `price`, not local-currency `price_in_purchased_currency`. Trials add no paid revenue. Customer-support/refund cancellations contribute a negative refund amount. Revenue is gross before store fees and taxes.

Active subscriptions and estimated MRR use observed billing history. Renewal/churn percentages require matured observed paid periods and a seven-day outcome window; missing history is excluded. Do not interpret a pending webhook or absent backfill as zero historical revenue.

## Verify

Send RevenueCat's test webhook and confirm receipt status, then make a real sandbox purchase to validate subscription normalization and the user's journey. A TEST payload alone does not validate purchase revenue. Open Submetry with `sandbox` selected; production events remain separate. Without a shared user ID, server events can arrive but cannot join the app journey reliably.

See [Quickstart](https://submetry.com/docs/quickstart.md), [Events](https://submetry.com/docs/events.md) and [Managing apps](https://submetry.com/docs/apps.md).
