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 → Integrations → 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.

Match the environments. A test connection accepts sandbox events. A live connection accepts production events.

Know which events FounderHQ reads

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

Purchases, renewals, and refunds move money. 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

Send a test webhook from RevenueCat. The connection shows Connected.
Buy a sandbox subscription in your app.
In FounderHQ, open Revenue. The purchase shows the channel that brought the customer.

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 a live connection, or the reverse. Create a connection in the matching environment.

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