Pushlane: Match RevenueCat App User IDs to Push Tokens

A RevenueCat webhook can tell you that a subscription changed. An APNs device token can tell Apple where to deliver a notification. Neither value, by itself, tells your push system that they belong to the same person.

That missing connection is why an apparently healthy integration can receive every purchase event and still fail to notify the subscriber who made the purchase. The webhook contains an app_user_id. The device registration contains a token scoped to one app on one device. Your own stable user ID is the bridge between them.

The reliable model is simple: identify the person with the same value in RevenueCat and Pushlane, then let each system keep the identifier it owns. RevenueCat owns subscription identity and history. APNs owns device addresses. Pushlane stores the relationship between your user and the reachable device.

The three identifiers have different jobs

Treating these values as interchangeable creates subtle bugs. They represent three different things:

Apple describes the APNs token as an address unique to the app and device. It also tells developers to request that token when the app launches and forward it to the provider server. A token is not an account ID, and Apple explicitly notes that the same token cannot be used for two apps. See Registering your app with APNs.

RevenueCat uses the App User ID differently. It is the customer identifier used across its dashboard, APIs, webhooks, and integrations. RevenueCat can generate an anonymous ID, or you can provide a custom one. Its official customer identification guide recommends unique, non-guessable custom IDs and warns against emails, advertising IDs, and hardcoded values.

The practical rule is this:

Pass the same stable, non-guessable account ID to RevenueCat and Pushlane. Never use the APNs token as the RevenueCat App User ID.

How the join works in Pushlane

On iOS, Pushlane provides identifyForRevenueCat so the shared ID is established at one call site:

import RevenueCat
import PushlaneCore

let userID = Pushlane.identifyForRevenueCat(currentUser.id)
Purchases.configure(withAPIKey: "appl_...", appUserID: userID)

When that user logs in later or switches accounts, keep both SDKs synchronized:

Purchases.shared.logIn(userID) { _, _, _ in }
Pushlane.identifyForRevenueCat(userID)

This does not send purchase events from the phone. RevenueCat sends subscription events to Pushlane through a server-to-server webhook. Pushlane resolves the webhook's original_app_user_id, current app_user_id, and aliases to a canonical user, then emits server-side flow events such as revenuecat.billing_issue or revenuecat.cancellation.

Separately, the Pushlane SDK registers the installation and its APNs token against that same user. When a flow decides to send, Pushlane can select the iOS device registration associated with the resolved user. The purchase signal and the push address meet through the shared ID, not through client-side purchase tracking.

The full webhook setup, including the dedicated authorization secret, is covered in RevenueCat + Pushlane integration.

Why anonymous RevenueCat IDs need deliberate handling

If you configure RevenueCat without an App User ID, its SDK creates an anonymous value prefixed with $RCAnonymousID:. RevenueCat documents that this cached ID can change after an uninstall and reinstall. That behavior is valid for anonymous products, but it complicates push attribution when your notification system knows the person by a different account ID.

You have two reasonable identity strategies.

Identify before configuration. If the app requires an account before a purchase, provide your stable account ID when configuring RevenueCat and identify that same ID in Pushlane. This is the cleanest path because the first purchase is attributed to the same identity used for device registration.

Start anonymous, then log in both systems together. If users can browse or purchase before creating an account, let RevenueCat begin anonymously. When an account becomes known, call RevenueCat logIn with your stable ID and identify the same ID in Pushlane. RevenueCat may merge or transfer identities according to the project's restore behavior.

RevenueCat includes associated IDs in the webhook aliases array and identifies one value as original_app_user_id. Pushlane's webhook resolver considers those identity fields. That makes normal RevenueCat aliasing manageable, but it is not a reason to let the two SDKs drift. A deterministic shared ID remains the primary contract.

Avoid calling RevenueCat logOut as a routine way to switch known accounts if your identity design expects custom IDs only. RevenueCat documents that logOut creates a new anonymous App User ID. For an account switch, log in to the next known ID and update Pushlane at the same boundary.

Device tokens are installation state, not customer state

A person may have an iPhone and an iPad. A shared family device may be used by two accounts. One person may reinstall the app and receive a new token. These are ordinary conditions, not edge cases.

Your data model must therefore allow:

• one user to have more than one device registration;
• one installation's token to be refreshed;
• a device registration to move when a different account signs in;
• invalid or unregistered tokens to stop being considered reachable;
• subscription identity to survive even when no reachable device currently exists.

Do not copy a token into a RevenueCat customer attribute and treat that as the source of truth. It creates a stale, one-token snapshot in a system whose job is subscription state. Device registration belongs in the push provider, where token rotation, platform, environment, and reachability can be handled as delivery concerns.

Pushlane's proven delivery path is iOS through APNs. Pushlane can register Android FCM tokens and show Android reachability, but Android push delivery is not supported yet. Do not interpret a registered Android token as an end-to-end delivery guarantee.

A login sequence that avoids cross-account sends

Account switching deserves special care because the phone stays the same while the person changes. Use one ownership transition in your app:

1. Complete authentication and obtain the new stable account ID.
2. Call RevenueCat logIn with that ID.
3. Call Pushlane.identifyForRevenueCat with the exact same value.
4. Reapply user attributes that belong to the new account.
5. Only then enable account-specific messaging or purchase actions.

Do not normalize one ID differently in each SDK. RevenueCat App User IDs are case-sensitive. If one side receives User_42 and the other receives user_42, you have created two identities even if your database treats them as equivalent.

Also avoid mutable identifiers. Email addresses can change, expose personal information, and are discouraged by RevenueCat. A database UUID or another opaque account key is a better join key. If your product has workspaces as well as people, decide whether purchases belong to a person or workspace and use that ownership model consistently. Do not alternate between both.

Verify the identity path before writing lifecycle copy

Test the join as a sequence, not as three isolated integrations.

Confirm the RevenueCat customer. In the RevenueCat dashboard, search for the exact custom App User ID. RevenueCat recommends exposing this ID in an app settings or support screen because it makes customer troubleshooting easier.

Confirm the Pushlane user and device. The same external ID should have an iOS device registered. A webhook can resolve correctly while the user remains unreachable because notification permission was denied, token registration failed, or the app was uninstalled.

Send RevenueCat's authenticated test event. This proves the webhook URL and its dedicated rcw_... authorization secret. It does not prove that a real lifecycle event will match an installed device.

Exercise a sandbox purchase with a unique test account. Inspect the real webhook identity fields and verify that the corresponding server-side revenuecat.* event reaches the expected flow. Keep sandbox and production behavior distinguishable in your flow conditions.

Test logout and account switching. Sign in as account A, then account B on the same device. A subscription event for A must not select B's current device registration merely because the token was once associated with A.

Test reinstall behavior. Reinstall, sign in with the same account ID, and confirm that the new APNs registration restores reachability without creating a new subscription identity.

Diagnose failures from the middle

When a push does not arrive, start with the shared ID. It narrows the problem faster than changing copy or resending webhooks.

If the RevenueCat webhook was never received, inspect webhook configuration and authorization. If it was received but resolved to an unexpected user, compare app_user_id, original_app_user_id, aliases, and the ID passed to Pushlane. If the correct flow entered but delivery was suppressed, inspect iOS device reachability, consent, APNs credentials, and token validity. If APNs accepted the send but the user did not see it, inspect notification presentation and device settings.

This separation matters. Subscription ingestion, identity resolution, flow decisions, and push delivery are distinct stages. A successful stage should not be used as proof that every later stage worked.

The implementation rule to keep

You do not match a RevenueCat App User ID directly to an APNs token. You match both to the same customer identity:

RevenueCat webhook app_user_id
              |
              v
       stable account ID
              |
              v
Pushlane user -> current iOS APNs device registration

Keep the account ID stable, opaque, case-consistent, and synchronized at every login change. Let RevenueCat manage subscription aliases. Let Pushlane manage device registrations. That boundary gives a billing event a reliable route to the right reachable iOS installation without pretending that a device token is a person.