Why the RevenueCat App User ID Must Match the Experiment User ID

When a user makes a purchase, RevenueCat receives the transaction from Apple or Google, processes it, and sends a webhook to your configured endpoint. This webhook includes the App User ID that was active when the purchase occurred, along with transaction details like product identifier, price, and timestamp. Your attribution system receives this webhook and needs to look up which experiment variant this user was assigned.

The lookup only works if the user ID in the webhook matches a user ID in your experiment assignment records. If RevenueCat says user "abc123" purchased and your experiment system has no record of assigning "abc123" to a variant, that purchase becomes unattributable. It might count toward overall revenue, but it won't influence experiment results because you can't determine which experience led to it.

The most frequent mismatch happens when apps set the RevenueCat App User ID at a different point in the user lifecycle than experiment assignment. For example, the experiment might assign a variant immediately on app launch using an anonymous analytics ID, while RevenueCat doesn't receive an App User ID until after account creation. The user who saw the onboarding variant and the user who made the purchase appear to be different people.

Another common issue is using different ID formats or sources. The experiment platform might use an advertising ID or device ID, while RevenueCat gets set with a backend-generated user UUID. Even if these represent the same person, string comparison will fail. Case sensitivity can cause problems too—"User123" and "user123" are different strings even though you intended them to reference the same account.

The cleanest approach is to generate or retrieve a single canonical user ID as early as possible in the app lifecycle, then use that same ID for both RevenueCat and experiment assignment. Many apps generate a UUID on first launch, store it in persistent device storage, and use it consistently across all third-party integrations. This works for anonymous users and persists even if they later create an account.

If you need to identify users before they create accounts, make sure both systems receive the anonymous ID. When users do create accounts, handle the identifier transition carefully. RevenueCat supports aliasing, which lets you associate the anonymous App User ID with a new account-based ID. Your experiment system needs to maintain the same mapping so that pre-signup variant assignments remain connected to post-signup purchases.

Before launching an onboarding experiment, verify that user IDs match by examining both systems' data. Pick a test user ID, assign them to an experiment variant, then check what App User ID RevenueCat shows for that same user. They should be identical. If they're not, trace through your initialization code to find where the divergence happens.

Monitor attribution rates once the experiment runs. If you're seeing far fewer attributed purchases than total purchases in RevenueCat, you have an ID mismatch problem. Calculate the percentage of webhook events that successfully match to an experiment variant. Rates below 95% indicate systematic identification issues that need immediate investigation.

Some apps use different identifiers across platforms or app versions, creating challenges for consistent experimentation. Document your ID strategy clearly and enforce it through code review and integration tests. If you must change identification schemes, plan a migration period where you maintain both old and new IDs to avoid losing attribution during the transition.

Platforms like Spinosis explicitly require that the App User ID in RevenueCat matches the experiment user ID to enable accurate purchase attribution. This isn't an arbitrary technical limitation—it's fundamental to causal inference. When you run controlled experiments, you need to know exactly which treatment each user received. Mismatched identifiers break that certainty and invalidate your results.