Copy as markdown[View .md](https://docs.funnelfizz.com/quickstart/connect-stripe "View the raw markdown for this page")[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs.funnelfizz.com%2Fquickstart%2Fconnect-stripe.md%20and%20help%20me%20with%20this%20FunnelFizz%20topic%3A%20Connect%20Stripe "Open this page in Claude with context")[Open in ChatGPT](https://chat.openai.com/?q=Read%20https%3A%2F%2Fdocs.funnelfizz.com%2Fquickstart%2Fconnect-stripe.md%20and%20help%20me%20with%20this%20FunnelFizz%20topic%3A%20Connect%20Stripe "Open this page in ChatGPT with context")

# Connect Stripe

Stripe is how FunnelFizz tells the difference between "someone visited your site" and "someone is paying you." It's technically optional — you can track up through CONSIDERATION with just the tracking snippet — but without Stripe, your TRIAL and CUSTOMER stages will sit at zero.

There are two ways to connect. Both produce the same thing: a read-only Stripe API key stored encrypted in FunnelFizz.

## Option A: Paste a restricted API key (recommended today)[​](#option-a-paste-a-restricted-api-key-recommended-today "Direct link to Option A: Paste a restricted API key (recommended today)")

This takes about 60 seconds.

### 1. Create the key in Stripe[​](#1-create-the-key-in-stripe "Direct link to 1. Create the key in Stripe")

In your Stripe dashboard:

1. Go to **Developers → API keys** (or [dashboard.stripe.com/apikeys](https://dashboard.stripe.com/apikeys)).

2. Click **Create restricted key**.

3. Name it `FunnelFizz (read-only)`.

4. Set these **seven** permissions to **Read**:

   <!-- -->

   * Customers
   * Charges and Refunds
   * Events
   * Products and Prices
   * Invoices
   * Subscriptions
   * Balance

5. Leave everything else as **None**.

6. Click **Create key**, then **Reveal key**.

7. Copy the key — it starts with `rk_live_...` (or `rk_test_...` if you're on a test account).

:::warning Exactly these seven FunnelFizz validates every permission in parallel when you paste the key. If you miss one, you'll get a specific error like *"missing read access for: Subscriptions, Invoices."* Just add those scopes in Stripe and click "Update key." :::

### 2. Paste it into FunnelFizz[​](#2-paste-it-into-funnelfizz "Direct link to 2. Paste it into FunnelFizz")

In the onboarding wizard (or at any time from **Settings → Integrations**):

1. Click **Connect Stripe**.
2. Paste the `rk_live_...` key.
3. Click **Validate**.

FunnelFizz pings each scope (`customers.list`, `subscriptions.list`, etc.), fetches your account name, and stores the key encrypted. You'll see a green checkmark with your Stripe account name.

### 3. Map your products[​](#3-map-your-products "Direct link to 3. Map your products")

Once connected, FunnelFizz auto-detects your Stripe products and offers to wire them into your funnel's conversion points:

* **Trial conversion** (CONSIDERATION → TRIAL) maps to Stripe subscriptions with `status="trialing"`.
* **Paid conversion** (TRIAL → CUSTOMER) maps to Stripe subscriptions with `status="active"`.

If you have multiple products, pick the one that represents your primary paid tier. You can always add more later — each product can define its own conversion.

## Option B: Install the Stripe App (one-click)[​](#option-b-install-the-stripe-app-one-click "Direct link to Option B: Install the Stripe App (one-click)")

The **FunnelFizz Stripe App** is on the [Stripe Apps Marketplace](https://marketplace.stripe.com/). Under the hood it creates the same restricted key as Option A, but the workflow is simpler:

1. Search "FunnelFizz" in the Stripe Apps Marketplace.
2. Click **Install**. Stripe shows a consent screen with the seven read permissions already checked.
3. Click **Generate** — Stripe creates the key automatically.
4. The app's settings view appears with the new `rk_live_...` key.
5. Click the **Open FunnelFizz** deep link — the key is auto-forwarded and connected.

The end state is identical to Option A. Pick whichever feels easier.

## What FunnelFizz does with your Stripe data[​](#what-funnelfizz-does-with-your-stripe-data "Direct link to What FunnelFizz does with your Stripe data")

Once connected, FunnelFizz:

* **Syncs every 15 minutes** — pulls customers, active subscriptions, trials, recent charges.
* **Listens to webhooks** — Stripe pushes `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, and `invoice.payment_failed` events so your funnel updates in near-real-time.
* **Computes stage entry** — when a tracked visitor becomes a Stripe customer, a **journey event** is written linking their anonymous sessions to the paying customer record.
* **Calculates churn** — using a trichotomy: *Retained* (still paying at your anchor tier), *Upgraded* (paying at a higher tier), or *Churned* (no active subscription anywhere).

## One Stripe account per workspace[​](#one-stripe-account-per-workspace "Direct link to One Stripe account per workspace")

FunnelFizz enforces a 1:1 relationship between Stripe accounts and workspaces. If you try to connect a Stripe account that's already in another workspace, you'll get an error. This is deliberate — it prevents accidental double-attribution across multiple tenants.

If you need to move a Stripe account between workspaces, disconnect it from the first workspace first, then reconnect in the new one.

## Using test mode[​](#using-test-mode "Direct link to Using test mode")

For development, generate an `rk_test_...` key with the same seven scopes. FunnelFizz handles both live and test keys. Test-mode Stripe events flow to your funnel just like live ones, so you can dry-run your setup without real charges. Just be aware that the **Livemode** flag is visible in your dashboard and your team will see which mode is connected.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

* **"Missing scopes" error.** Go back to Stripe → API keys → click your key → **Edit** → add the missing scopes → **Update key** → paste the key into FunnelFizz again.
* **Key says "test" but my subs are live (or vice versa).** You generated the key in the wrong Stripe mode. Toggle to the right mode in Stripe and regenerate.
* **No customers showing up.** Wait 15 minutes for the first sync, or click **Sync now** in **Settings → Integrations → Stripe**.
* **Stripe webhook not firing.** FunnelFizz auto-configures webhooks when you connect via the Stripe App. For API-key mode, webhooks are optional — polling syncs every 15 minutes covers most use cases. If you need real-time, add a webhook endpoint in Stripe pointing to `https://funnelfizz.com/api/webhooks/stripe` and copy the signing secret into your FunnelFizz Stripe integration settings.

***

**Next:** [Connect providers →](https://docs.funnelfizz.com/quickstart/connect-providers.md)