Connect RevenueCat

Connect RevenueCat so FounderHQ records App Store and Google Play purchases that RevenueCat already manages. This takes about ten minutes.

Before you start

You need a FounderHQ brand, the FounderHQ mobile SDK in your app (React Native, iOS, Android), and a RevenueCat project.

Follow the identity contract

This is the part that decides whether the connection works at all.

The FounderHQ mobile UUID is the RevenueCat App User ID. Not a copy of it. Not a mapped value. The same string.

Hand your RevenueCat client to the FounderHQ SDK at start-up, and the SDK keeps the two identities equal for you:

import Purchases from "react-native-purchases";
import { FounderHqEvents } from "@founderhq/events-react-native";

export const founderhq = new FounderHqEvents("fhq_pk_XXXX", {
  revenueCat: {
    configure: (appUserId) =>
      Purchases.configure({ apiKey: "rc_XXXX", appUserId }),
    logIn: (appUserId) => Purchases.logIn(appUserId),
  },
});

The SDK then:

configures RevenueCat with the FounderHQ UUID at start-up,
calls RevenueCat logIn when you identify a person,
calls logIn with a fresh UUID when you reset.

Never call Purchases.logOut()

logOut() makes RevenueCat mint its own anonymous ID. FounderHQ then cannot map the customer back to a contact, and the purchases arrive unattributed. To sign a person out, use the FounderHQ SDK's reset. It logs RevenueCat in as the new guest.

Create the connection in FounderHQ

In FounderHQ, open Settings → Revenue. Choose RevenueCat, the brand.

Enter the App Store bundle ID, the Google Play package name, or both, for the apps this RevenueCat project sells.

FounderHQ gives you a webhook URL:

https://app.getfounderhq.com/api/hooks/payments/revenuecat/CONNECTION_ID

Add the webhook in RevenueCat

In RevenueCat, open Integrations and add a webhook with that URL.

RevenueCat authenticates with an Authorization header value that you choose. Enter the same value in both places: the RevenueCat webhook and the FounderHQ connection. Treat it like a password.

FounderHQ tracks live purchases only. It refuses sandbox events.

Know which events FounderHQ reads

INITIAL_PURCHASE          NON_RENEWING_PURCHASE      RENEWAL
CANCELLATION              UNCANCELLATION             BILLING_ISSUE
SUBSCRIPTION_PAUSED       PRODUCT_CHANGE             EXPIRATION
REFUND_REVERSED           TRANSFER                   TEMPORARY_ENTITLEMENT_GRANT
PRICE_INCREASE_CONSENT_REQUIRED                      PRICE_INCREASE_CONSENT_APPROVED

Purchases and renewals move money. A refund arrives as a negative amount on one of them. Cancellations, billing issues, pauses, and price-consent events update state only.

Wrap the purchase call

Wrap your existing RevenueCat purchase so the store transaction reaches FounderHQ:

const result = await founderhq.purchaseWithRevenueCat(() =>
  Purchases.purchasePackage(pkg),
);

The wrapper returns your original result unchanged. See mobile purchase claims for the full purchase flow, including accounts.

Verify

The connection shows Connected after RevenueCat delivers the first production event from the list above.
Wait for the next real purchase in your app. FounderHQ tracks live purchases only and refuses sandbox events.
In FounderHQ, open Analytics → People and open the customer. The payment is on their Revenue tab.
Open Analytics → Overview. In the Channel card, ranked by Revenue, the payment counts for the channel that brought the customer. Switch between Closed by and Introduced by to see the last visit before the payment, or the first.

Troubleshoot

RevenueCat shows "Invalid authorization"

The Authorization header value in RevenueCat differs from the value stored on the connection. Set both to the same string.

RevenueCat shows "This endpoint only accepts production events."

A sandbox event reached FounderHQ. It tracks live purchases only, so this purchase is not recorded. Production purchases arrive normally.

Purchases arrive with no contact

Something called Purchases.logOut(), or configured RevenueCat with your own user ID. Remove those calls and let the FounderHQ SDK own the App User ID.

When you also sell through Stripe or a native store

RevenueCat is a transport, not the last word on the money. A direct Apple, Google Play, or Stripe connection wins for the same purchase.

You can add one at any time, for an app RevenueCat already reports. FounderHQ allows it, hands the money to the store from that moment, and leaves this connection in place as evidence — no downtime, no double counting, and nothing already recorded is lost. See multiple providers.

AI agent or LLM? Read this page as markdown

On this page