> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flokitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Connect Stripe to pull web subscription payments, revenue data, and refunds into FloKit.

## What FloKit reads from Stripe

Once connected, FloKit ingests the following Stripe data:

* Subscription objects: status, plan, billing interval, and amount
* Invoice payment successes and failures
* Refunds and dispute outcomes
* Customer metadata (including any `user_id` or external identifier fields you store on the customer object)
* Coupon and promotional discount redemptions
* Trial period starts and trial-to-paid conversions

FloKit does not read payment instrument details, raw card data, or any PCI-scoped fields from Stripe.

***

## Required access

Create a **Stripe restricted API key** with the following read-only permissions:

| Resource      | Permission |
| ------------- | ---------- |
| Customers     | Read       |
| Subscriptions | Read       |
| Invoices      | Read       |
| Charges       | Read       |
| Refunds       | Read       |

Do not grant write permissions. FloKit never needs to create, update, or delete Stripe objects.

Found in **Stripe Dashboard → Developers → API Keys → Create restricted key**.

***

## Setup

<Steps>
  <Step title="Create a restricted API key in Stripe">
    In **Stripe Dashboard → Developers → API Keys**, click **Create restricted key**. Name it `flokit-read` or similar. Grant **read** access to Customers, Subscriptions, Invoices, Charges, and Refunds. Save the key — you will not be able to view it again after leaving this page.
  </Step>

  <Step title="Add Stripe in FloKit">
    In **FloKit → Settings → Integrations → Subscriptions**, select **Stripe**. Enter your restricted API key.

    FloKit will automatically detect your Stripe account mode (live vs. test). Only live mode data is ingested.
  </Step>

  <Step title="Configure a Stripe webhook (recommended)">
    In **Stripe Dashboard → Developers → Webhooks**, click **Add endpoint**. Paste the FloKit webhook URL shown in the integration settings panel. Subscribe to the following events:

    ```
    customer.subscription.created
    customer.subscription.updated
    customer.subscription.deleted
    invoice.payment_succeeded
    invoice.payment_failed
    charge.refunded
    ```

    Webhooks enable real-time event delivery alongside the polling API.
  </Step>

  <Step title="Map your user identifier">
    FloKit joins Stripe customers to your other data sources using either `customer.email` or a metadata field on the Stripe customer object. In **FloKit → Settings → Integrations → Stripe → Identity mapping**, specify which field to use.

    If your backend sets `metadata.user_id` on the Stripe customer at checkout, use that field. Email-based joins work for most web-only setups.
  </Step>

  <Step title="Wait for historical backfill">
    FloKit begins a historical backfill immediately after the API key is saved. For most accounts, 90 days of subscription and invoice history loads within 2–4 hours. Progress is visible in **FloKit → Data → Sources → Stripe**.
  </Step>
</Steps>

***

## Validation checklist

* [ ] Stripe restricted API key added to FloKit with correct read permissions
* [ ] Subscription events visible in **FloKit → Data → Events**
* [ ] Customer identity resolving in **FloKit → Data → Identity**
* [ ] Webhook delivering events (check **FloKit → Data → Sources → Stripe → Recent events**)
* [ ] Revenue appearing in **FloKit → Reports → Revenue** with expected MRR range

***

## Common issues

**No subscriptions appearing after connecting**

Check that the restricted key has read access to Subscriptions and Customers. A key missing either permission will fail silently. Also confirm you are using a live mode key — test mode data is excluded from FloKit.

**Revenue totals differ from Stripe dashboard**

FloKit uses invoice amounts net of Stripe fees by default. If your Stripe dashboard shows gross amounts, the difference is Stripe's processing fee. You can configure the revenue calculation method in **FloKit → Settings → Revenue → Stripe fee handling**.

**Customer identity not joining to attribution**

If your web subscription flow does not pass a user identifier to Stripe (e.g. anonymous checkout), FloKit will fall back to email-based joins. Email-to-attribution joins are available if your MMP or product analytics platform captures email. See [Identity mapping](/send-data/identity-mapping).

**Webhook events arriving out of order**

Stripe delivers webhooks at least once, not in strict order. FloKit handles out-of-order events for all subscribed event types. Duplicate events are deduplicated automatically by event ID.

***

## A note on Stripe vs. mobile in-app purchases

Stripe is designed for web subscription flows — checkout pages, web-to-app funnels, and SaaS billing. For iOS and Android in-app purchases processed through the App Store or Google Play, use [RevenueCat](/integrations/revenuecat) or [Adapty](/integrations/adapty). These platforms handle the App Store and Play Store receipt validation that Stripe does not touch.

Many apps have both Stripe (web) and RevenueCat (mobile). Both can be connected simultaneously — FloKit deduplicates revenue across sources.

***

## What this unlocks in FloKit

* Web subscription MRR and ARR tied to acquisition campaigns
* Trial-to-paid conversion rates for web checkout flows
* Refund and churn rates by cohort and acquisition source
* Coupon and discount impact on net revenue and LTV
* Cross-channel payback when web and mobile subscriptions are combined