Skip to main content

​
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:
ResourcePermission
CustomersRead
SubscriptionsRead
InvoicesRead
ChargesRead
RefundsRead
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

1

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

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

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.
4

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.
5

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.

​
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. 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 or 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