RevenueCat integration

If your app sells through RevenueCat, AppRefer reads RevenueCat’s webhooks to tie each purchase to its ad click and send it to your ad networks, with no purchase tracking code in the app.

New apps: use AppRefer Billing

RevenueCat stays supported for apps that use it. AppRefer Billing does the same job itself for the App Store, Google Play and Stripe (purchases, entitlements, offerings, experiments and conversions), with no data export needed to move over, and this webhook keeps working for old app versions during the switch. See Billing and Moving from RevenueCat. For prices and what each does that the other doesn't, see AppRefer vs RevenueCat.

Why webhooks

Renewals, cancellations, billing issues and expiries arrive even when the app is closed.
No purchase events to track in the app.
One source for the whole subscription lifecycle.

Set up

In AppRefer, open the app’s Settings → Integrations → RevenueCat and click Generate to create a webhook secret. The app’s webhook URL is shown there too.
In RevenueCat → Project settings → Integrations → Webhooks, add a webhook with the URL https://apprefer.com/api/webhook/revenuecat/{appId} (your own domain if you host AppRefer yourself).
Set the Authorization header value to Bearer <your secret>. Any other value gets 401.
Send all event types. Sandbox events are accepted, recorded as sandbox and never sent to ad networks.
Send a test event from RevenueCat and check that it shows up in the app’s Live events page.

Link the AppRefer device id

Required for attribution

Set the appreferId subscriber attribute in RevenueCat to the AppRefer device id. It is the surest way for AppRefer to find the install, and its ad click, behind each RevenueCat event.

Call this right after configuring AppRefer, before the user can buy anything:

await AppRefer.configure(apiKey: "pk_live_...")
if let deviceId = await AppRefer.getDeviceId() {
    Purchases.shared.attribution.setAttributes(["appreferId": deviceId])
}

For each event, AppRefer looks for the install’s attribution in this order:

The appreferId attribute ($appreferId is also read).
The RevenueCat app user id, original app user id and aliases, matched to the user id you set with AppRefer’s setUserId.
The $idfa or $gpsAdId attribute.
The hashed $email attribute.

With no match the event is still recorded (as unattributed), and paid purchases are still sent to your connected ad networks (Meta, TikTok and ChatGPT Ads, and Google when a gclid is known), which credit only what they can match. RevenueCat’s $ip, $email, $phoneNumber and $displayName attributes are used for matching quality when present.

Event mapping

RevenueCat event	AppRefer event
INITIAL_PURCHASE	startTrial (trial period), intro_purchase (intro offer), promo_purchase (promotional), otherwise purchase
RENEWAL	purchase (trial conversions are flagged is_trial_conversion)
PRODUCT_CHANGE	subscribe
NON_RENEWING_PURCHASE	purchase
CANCELLATION	cancellation
UNCANCELLATION	reactivation
BILLING_ISSUE	billing_issue
SUBSCRIPTION_PAUSED	pause
SUBSCRIPTION_EXTENDED	subscription_extended
EXPIRATION	expiration
TRANSFER	transfer
Anything else	The RevenueCat type in lower case

What is sent to ad networks

Event	Sent?
INITIAL_PURCHASE, paid	Yes
INITIAL_PURCHASE, free trial	Only as StartTrial when qualified trials are on for an attributed install (held for the delay, dropped if cancelled)
RENEWAL, paid	Yes. Trial conversions always; ordinary renewals unless renewal forwarding is off for the app
NON_RENEWING_PURCHASE	Yes
PRODUCT_CHANGE, CANCELLATION, UNCANCELLATION, BILLING_ISSUE, SUBSCRIPTION_PAUSED, EXPIRATION, TRANSFER and others	No (recorded only)
Any sandbox event	No

Meta follows RevenueCat’s recommended mapping: a subscription’s first payment, its trial conversion and every renewal are Subscribe, one-time purchases are Purchase and trial starts are StartTrial. You can change the names in the app’s Meta integration settings. Forwarding also follows each install’s tracking consent (see Privacy). Qualified trials keep the purchase surface and the user’s IP and user agent through the delay and retries, so web-funnel trials still go to the web-funnel Meta dataset.

Duplicates

RevenueCat may deliver an event more than once. AppRefer processes each event id once and remembers processed ids for 30 days.

Alongside AppRefer Billing

When an app runs AppRefer Billing in primary mode, keep this webhook connected while old app versions still buy through RevenueCat. For each store AppRefer Billing is connected to, RevenueCat’s events are no longer forwarded from here: AppRefer saves which app user owns the purchase so later store notifications find them, and money events share AppRefer Billing’s transaction-based id, so each purchase is forwarded once. Stores not connected to AppRefer Billing keep the full RevenueCat path. Once AppRefer’s own Stripe webhook is set up, RevenueCat’s Stripe events are skipped so web purchases aren’t counted twice.