# Connect RevenueCat (https://www.getfounderhq.com/docs/analytics/revenue/connect-revenuecat)

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

<Callout title="Before you start">
  You need a [FounderHQ brand](/analytics/getting-started), the FounderHQ mobile
  SDK in your app ([React Native](/analytics/sdks/react-native),
  [iOS](/analytics/sdks/ios), [Android](/analytics/sdks/android)), and a
  RevenueCat project.
</Callout>

## 1. 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:

```ts
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.

<Callout type="warn" title="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.
</Callout>

## 2. 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:

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

## 3. 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.

## 4. Know which events FounderHQ reads

```text
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.

## 5. Wrap the purchase call

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

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

The wrapper returns your original result unchanged. See
[mobile purchase claims](/analytics/revenue/mobile-purchase-claims) for the full
purchase flow, including accounts.

## Verify

1. Send a test webhook from RevenueCat. The connection shows **Connected**.
2. Buy a sandbox subscription in your app.
3. 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](/analytics/revenue/multiple-providers).