Copy as markdown[View .md](https://docs.funnelfizz.com/getting-started/connect-stripe "View the raw markdown for this page")[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs.funnelfizz.com%2Fgetting-started%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%2Fgetting-started%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 distinguishes "someone visited your site" from "someone is paying you." Without it, TRIAL and CUSTOMER stages stay at zero.

Two ways to connect, both store the same encrypted read-only API key.

## Option A: Paste a restricted API key (\~60s)[​](#option-a-paste-a-restricted-api-key-60s "Direct link to Option A: Paste a restricted API key (~60s)")

1. **Stripe dashboard → Developers → API keys → Create restricted key**.

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

3. Set these **seven** permissions to **Read** (everything else **None**):

   | Customers             | Charges & Refunds | Events            |
   | --------------------- | ----------------- | ----------------- |
   | **Products & Prices** | **Invoices**      | **Subscriptions** |

4. **Create key → Reveal**. Copy the `rk_live_…` (or `rk_test_…`).

5. In FunnelFizz: **Connect Stripe** → paste → **Validate**. We probe each scope in parallel and surface any missing one with a specific error message.

## 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)")

Search "FunnelFizz" on the [Stripe Apps Marketplace](https://marketplace.stripe.com/). The app creates the same restricted key automatically, then deep-links you back to FunnelFizz with the key pre-filled. Webhooks are auto-configured.

## What we do with the data[​](#what-we-do-with-the-data "Direct link to What we do with the data")

* **Replay your history on connect.** All your existing Stripe customers retroactively land on the right funnel stages with their actual historical timestamps. Cohort cards show pre-existing customers immediately — you don't have to wait for the next webhook.
* **Sync every 15 minutes**. Customers, subscriptions, trials, charges.
* **Listen to webhooks**, `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed` for near-real-time updates.
* **Stitch identities**. When a tracked visitor becomes a Stripe customer, journey events link their anonymous sessions to the paying record.
* **Compute the churn trichotomy**, Retained / Upgraded / Churned (see [stages](https://docs.funnelfizz.com/concepts/stages.md#customer--paying-customers)).

## What backfill can and can't resolve[​](#what-backfill-can-and-cant-resolve "Direct link to What backfill can and can't resolve")

Replay also re-runs every time you create a funnel, add a [split](https://docs.funnelfizz.com/concepts/splitting.md) or [extension](https://docs.funnelfizz.com/concepts/extensions.md), or edit a [conversion](https://docs.funnelfizz.com/concepts/conversion.md). Existing customers slot into the new tracks at their real historical moments — period conversion graphs bucket them by when they actually became paid, not by when you set up the funnel.

Re-trials, upgrades, and churn are all reflected if Stripe knows about them.

**What replay CAN resolve**, working from Stripe + profile data:

| Track condition                  | Resolvable?                                                                            |
| -------------------------------- | -------------------------------------------------------------------------------------- |
| `stripe_product`, `stripe_price` | Yes, perfectly.                                                                        |
| `traffic_source`, `utm`          | Yes, when first-touch attribution was previously captured on the profile via tracking. |
| `geography`                      | Yes, when the profile already has a country set from prior tracking.                   |
| `device_type`                    | Yes, when previously captured.                                                         |

**What replay CAN'T resolve**:

* `channel`, `custom_event`, `ab` — these signals were never sent to Stripe and aren't recoverable.
* `geography`, `device_type`, `utm` for Stripe-only customers who never had a tracking event.

When a track condition can't be evaluated for a profile, the profile gets a `cohort_unresolvable_at_replay` event on its [activity timeline](https://docs.funnelfizz.com/concepts/users.md#cohort--automation-diagnostic-events) so you can see who needs manual resolution.

**What replay does NOT do**: trigger automations. Past-state customers don't get welcome emails. To message backfilled customers, create a one-shot campaign targeted at the relevant stage or split.

After Stripe connect, replay also fires automatically on funnel creation, on every new split or extension, and after conversion-config edits — so you usually don't need to think about it. After editing track conditions on an existing funnel, you can re-run it manually from the dashboard or via the [`replay_historical_journeys` MCP tool](https://docs.funnelfizz.com/ai-agents/mutations.md#funnel-mutations-scope-writefunnels).

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

A given Stripe account can only be connected to one workspace at a time, prevents double-attribution across tenants. Move accounts by disconnecting first.

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

`rk_test_…` keys with the same seven scopes work identically. Useful for dry-running setup without real charges. The dashboard shows which mode is connected.

## Linking Stripe to a funnel[​](#linking-stripe-to-a-funnel "Direct link to Linking Stripe to a funnel")

One Stripe connection per workspace, one logical link per funnel. Click **Connect Stripe** on a funnel (or call `link_stripe_to_funnel` over [MCP](https://docs.funnelfizz.com/ai-agents/mcp.md)), that one marker on the CUSTOMER stage is enough; data flows through every relevant stage and split branch automatically.

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

* *"Missing scopes"*, Stripe → edit the key → add scopes → Update → paste into FunnelFizz again.
* *Mode mismatch*, generated the key in the wrong mode. Toggle and regenerate.
* *No customers after 15 min*, click **Sync now** in **Settings → Integrations → Stripe**.
* *Webhook not firing (API-key mode only)*, the Stripe App handles this automatically. For API-key mode, add a webhook endpoint in Stripe pointing to `https://funnelfizz.com/api/webhooks/stripe` and paste the signing secret in the integration settings.

***

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