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

# RevenueCat

> Connect RevenueCat to pull subscription state, trials, renewals, cancellations, and refunds into FloKit.

## What FloKit reads from RevenueCat

Once connected, FloKit ingests the following RevenueCat events and subscriber attributes:

* Current subscriber status and entitlement grants/revocations
* Trial starts and trial-to-paid conversions
* Subscription starts, renewals, and plan changes
* Cancellations, refunds, and grace periods
* Billing issues and payment recovery events
* Offer redemptions and promotional entitlements
* Paywall experiment variants (if RevenueCat Experiments is in use)

FloKit does not read raw receipt data or payment instrument details from RevenueCat.

***

## Required access

**API key:** RevenueCat Project API key (v1, read-only). Found in **RevenueCat Dashboard → Project Settings → API Keys**.

Create a dedicated read-only key for FloKit. Do not share a key that has write or admin permissions.

**Required identifier:** `app_user_id` — RevenueCat's identifier for each subscriber. FloKit joins this field to your MMP's `customer_user_id` to link subscription outcomes to acquisition campaigns. If your app uses RevenueCat's anonymous IDs, see [Identity mapping](/send-data/identity-mapping) before connecting.

***

## Setup

<Steps>
  <Step title="Create a read-only API key in RevenueCat">
    In **RevenueCat Dashboard → Project Settings → API Keys**, create a new v1 API key. Set the permission level to **read-only**. Copy the key — you will not be able to view it again after leaving this page.
  </Step>

  <Step title="Add RevenueCat in FloKit">
    In **FloKit → Settings → Integrations → Subscriptions**, select **RevenueCat**. Enter your RevenueCat Project API key and your app's bundle ID (e.g. `com.yourapp.ios` for iOS, `com.yourapp` for Android).
  </Step>

  <Step title="Configure the RevenueCat webhook (recommended)">
    In **RevenueCat → Project Settings → Integrations → Webhooks**, add a new webhook destination. Paste the FloKit webhook URL shown in the FloKit integration settings panel. Enable delivery for all event types. This enables real-time event delivery alongside the polling API.
  </Step>

  <Step title="Wait for historical backfill">
    FloKit will begin a historical backfill immediately after the API key is saved. For most apps, 30–90 days of subscriber history loads within 2–4 hours. Backfill progress is visible in **FloKit → Data → Sources → RevenueCat**.
  </Step>
</Steps>

***

## Validation checklist

* [ ] RevenueCat API key added to FloKit with read-only permissions
* [ ] At least one subscriber event visible in **FloKit → Data → Events**
* [ ] `app_user_id` resolving in **FloKit → Data → Identity**
* [ ] Webhook delivering events (check **FloKit → Data → Sources → RevenueCat → Recent events**)
* [ ] Historical backfill shows expected subscriber count under **FloKit → Data → Sources → RevenueCat**

***

## Common issues

**No events appearing after connecting**

Check that the API key has read access to the correct RevenueCat project. A key scoped to a different project silently returns empty results. Sandbox and development environment events are excluded from FloKit by default — only production events are ingested.

**`app_user_id` not joining to attribution data**

FloKit joins `app_user_id` to your MMP's `customer_user_id`. If your RevenueCat and AppsFlyer/Adjust installations use different identifiers (e.g. a device ID vs. your internal user ID), the join will fail. See [Identity mapping](/send-data/identity-mapping) for resolution options.

**Missing refunds**

App Store refunds require Apple to notify RevenueCat, and Apple's notification latency is typically 24–72 hours after the refund is issued. If you are reconciling refunds against finance data, account for this lag.

**Paywall experiment variants missing**

RevenueCat experiment variant data is only available if you are using RevenueCat Experiments (A/B testing). If you run paywalls through a third-party tool like Adapty or a custom implementation, connect that source instead.

***

## What this unlocks in FloKit

* Trial-to-paid conversion rates by acquisition campaign, creative, and country
* Subscription renewal rates and churn curves by cohort
* Cancellation and refund drag on LTV
* LTV curves segmented by acquisition source
* Payback period reporting tied to spend data from connected ad platforms