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

Connect Superwall so FounderHQ records the purchases your paywalls make. It
takes your app's store identity and the signing secret Superwall gives you.
Allow about five minutes.

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

<Callout type="warn" title="Using Superwall with RevenueCat? Connect RevenueCat instead">
  When RevenueCat manages the subscriptions and Superwall runs in observer mode,
  RevenueCat sees every purchase and Superwall's own webhooks may not fire.
  Connect [RevenueCat](/analytics/revenue/connect-revenuecat) and stop here — one
  app connects once.
</Callout>

## What you are deciding

Superwall reports purchases it did not charge, and FounderHQ takes Superwall
at its word. That is the same trust it extends to RevenueCat, and it is enough
to see your revenue, your channels, and your MRR from day one. Three things
are worth knowing before you connect.

**Refunds arrive as negative amounts, and FounderHQ subtracts them.** Superwall
has no separate refund event: a give-back shows up as a negative amount on
whichever event carries it, and FounderHQ reads the sign, not the label.

**If Superwall misses an event, it is gone.** There is no way to ask Superwall
to resend an event you never received, and no history to catch up from.
Superwall retries a failed delivery for you, so this is rare — but when it
happens, that purchase stays missing.

**The direct store connections are stronger.** [Apple App
Store](/analytics/revenue/connect-apple) and [Google
Play](/analytics/revenue/connect-google-play) are signed by the stores
themselves and can fill in history. Connect them where you can. If you add one
later for this app, it takes over the money automatically — see
[below](#adding-a-store-connection-later).

## 1. Create the connection in FounderHQ

In FounderHQ, open **Settings → Integrations → Revenue**. Choose the brand,
then Superwall. Read the screen, choose **Continue**, and name the app: the
**App Store bundle ID**, the **Google Play package name**, or both — whichever
stores Superwall sells through.

Those names also reserve the app. If this app already reports to FounderHQ
through RevenueCat or a direct store connection, FounderHQ refuses the second
connection and names the one that holds it. Two reporters would count every
purchase twice.

FounderHQ gives you a webhook address:

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

## 2. Add the webhook in Superwall

In Superwall, open **Integrations → Webhooks** and add an endpoint with that
address. Select all nine events:

```text
initial_purchase       renewal              non_renewing_purchase
product_change         cancellation         uncancellation
billing_issue          subscription_paused  expiration
```

Superwall shows a signing secret starting with `whsec_`. Copy it back into
FounderHQ and save.

## 3. Pass the FounderHQ token on every purchase

FounderHQ needs one value to know which visitor bought:

```ts
const prepared = await founderhq.preparePurchase({ source: "app_store" });
// 1. Superwall forwards user attributes on every webhook.
Superwall.shared.setUserAttributes(["fhq_visitor": prepared.appAccountToken])
// 2. Pass the same value to StoreKit as appAccountToken, so Apple returns it
//    too — a direct App Store connection reads it from there.
```

Both carry the same UUID, and either one is enough. See [mobile purchase
claims](/analytics/revenue/mobile-purchase-claims) for the full flow, including
accounts.

## What FounderHQ records

| Superwall reports     | FounderHQ records                                                  |
| --------------------- | ------------------------------------------------------------------ |
| App Store purchases   | Superwall's amount and currency                                    |
| Google Play purchases | Superwall's amount and currency                                    |
| Stripe purchases      | Ignored — connect Stripe                                           |
| Refunds               | The negative amount on the event                                   |
| Lifecycle events      | Cancellations, pauses, billing issues, expirations move state only |

The price Superwall shows on its own dashboard is converted to US dollars and
its proceeds are estimated. FounderHQ never uses either. It reads only the
amount in the currency your customer actually paid.

Two more rules worth knowing:

- **Family Sharing.** A family member's renewal arrives at zero. It updates the
  subscription and adds no revenue.
- **Refunds for purchases FounderHQ never saw.** If a refund arrives for a
  purchase from before you connected, FounderHQ records the refund on the
  connection but does not subtract it — the purchase it reverses was never in
  your totals, so subtracting it would undercount your revenue.

**Stripe.** Connect [Stripe](/analytics/revenue/connect-stripe) directly.
Superwall's Stripe events carry no charge reference, so FounderHQ cannot tell
them apart from the ones Stripe already sends, and recording both would double
your totals.

## Adding a store connection later

This is the upgrade. Connect [Apple App
Store](/analytics/revenue/connect-apple) or [Google
Play](/analytics/revenue/connect-google-play) for this app whenever you are
ready. FounderHQ allows it, and from that moment the store owns the money:

- The store's amounts, taxes, and dates replace Superwall's.
- Superwall stays connected. Its events are kept as evidence and add nothing to
  your totals, so nothing is counted twice during the switch.
- Everything already recorded stays in your reports.

The reverse is not allowed: once a store connection owns an app, FounderHQ
refuses a second reporter for it. Disconnect the store connection first if you
really want to go back.

## Verify

1. Save the signing secret. The connection shows **Waiting for test**.
2. Make a purchase in your app. A TestFlight purchase works.
3. The connection shows **Connected**, and the purchase appears in Revenue with
   the channel that brought the customer.

Superwall has no send-a-test-event button, so a real purchase is what finishes
setup. This is the one connector that cannot turn on before your first sale.

## Troubleshoot

### Amounts look different from Superwall's dashboard

Superwall's dashboard converts everything to US dollars using its own rates.
FounderHQ records what your customer paid, in their currency, and converts with
published daily rates on the day of the purchase.

### The connection shows "This endpoint only accepts production events."

A sandbox event reached a live connection, or the reverse. Create a connection
in the matching environment.

### Nothing arrives at all

Confirm the endpoint in **Superwall → Integrations → Webhooks** has the
FounderHQ address and all nine events selected, and that the signing secret in
FounderHQ is the one Superwall shows for that endpoint.

### Purchases arrive without a channel

The app did not set `fhq_visitor` before the purchase. Call `preparePurchase`
and pass the value to `setUserAttributes` when your app starts, and to StoreKit
on every purchase.