Integrating Flex with RevenueCat - Flex Documentation

Overview

Flex integrates with RevenueCat to help you manage subscriptions seamlessly across platforms. This guide walks you through connecting your RevenueCat account to Flex, passing a stable customer identifier, saving the integration, and understanding how events map between systems.

Installation Guide

Flex + RevenueCat Integration - YouTube
Flex + RevenueCat Integration

1. Add RevenueCat in Flex
   Log in to your Flex Dashboard. Go to Integrations → RevenueCat. Enter your RevenueCat App ID and API Key.

   • You can find these in your RevenueCat project under App Settings.

2. Configure in RevenueCat
   In your RevenueCat project, open the Apps section. Click + Add and select Other payment provider. Copy your App ID and Secret API Key. Paste these values into the Flex Dashboard RevenueCat fields from Step 1.

If you don’t see “Other payment provider (External source)” in your RevenueCat Apps page, that option may not be enabled for your project. Please contact RevenueCat Support and ask them to enable the External payment provider integration for your project. Include:

• Your Project ID / link
• The App name
• That you want to connect Flex as the external payment provider

3. Pass a Custom User Identifier to RevenueCat
   If you want RevenueCat to reference your own user ID (or a Flex user ID), include it in the checkout session metadata as REVENUE_CAT_CUSTOMER_ID.

   {
     "checkout_session": {
       "line_items": [
         {
           "price": "fprice_01k2j2zfnbrs5e0r4c8wqphv29",
           "quantity": 1
         }
       ],
       "success_url": "https://example.com/thank-you?success=true",
       "mode": "subscription",
       "cancel_url": "https://example.com/thank-you?canceled=true",
       "shipping_address_collection": false,
       "defaults": {
         "first_name": "Varsha",
         "last_name": "Parthay",
         "email": "rclivedemo1@gmail.com"
       },
       "metadata": {
         "REVENUE_CAT_CUSTOMER_ID": "1234567890"
       }
     }
   }
   

4. Save and Sync
   Click Save in the Flex Dashboard integration page. Flex will begin sending subscription events to RevenueCat so customer status stays in sync.

   Tip: If you have existing subscriptions, run an initial sync (or perform a backfill) so historical subscriptions are recognized in RevenueCat.

How Flex Integrates with RevenueCat

There are two ways subscriptions can flow into RevenueCat:

Native Stripe Integration

Stripe sends webhooks directly to RC. RC processes them and generates events with store: "STRIPE".

Flex External Purchases API

Flex processes payments via Stripe, then syncs subscription state to RC via the External Purchases API (POST /v1/receipts/external). RC generates events with store: "EXTERNAL".

For Flex-managed subscriptions, all events come through the External Purchases API path. The subscription data is accurate and revenue is correctly tracked — but certain webhook fields have different values than a native Stripe integration would produce.

If you’re migrating from a native Stripe → RevenueCat integration, be aware of these key differences:

• store is "EXTERNAL", not "STRIPE" — update any webhook consumers that filter by store
• Refund events have price: 0.0, never negative — use the RC Subscriber API or Flex API for refund amounts
• expiration_reason is always null — use cancel_reason on preceding CANCELLATION events instead
• Prorated refunds are invisible in webhooks — no CUSTOMER_SUPPORT event is generated; use Flex API to detect partial refunds
• IDs use Flex format (fprod_, fsub_, fcus_) instead of Stripe format (prod_, si_, cus_) — treat all IDs as opaque strings

These differences are inherent to the RevenueCat External Purchases API and have been confirmed with the RevenueCat team (March 2026). Revenue is always accurately tracked inside RevenueCat — these differences only affect webhook payload fields.

Subscription Lifecycle Events

Flex syncs the following RevenueCat event types. This is the complete list — every event type that Flex sends to RC:

ProductChange (upgrades/downgrades) is not currently supported. All other subscription lifecycle events are fully implemented and synced in real-time.

Stripe Trigger Mapping

Each Flex RC sync event is triggered by a specific Stripe webhook event:

Event Sequences by Scenario

New Subscription (No Trial)

New Subscription (With Free Trial)

Both events appear as INITIAL_PURCHASE in RC webhooks. The first has price 0 and status trialing; the second has the actual price and status active.

Renewal

Payment Failure → Recovery

If payment never recovers, the subscription eventually receives an EXPIRATION event when Stripe deletes it.

Cancel at End of Billing Period (Option A)

Subscription remains active until the current period ends. Access continues during this time.

Undo Cancel / Re-subscribe Before Period Ends

Cancel Immediately + Full Refund (Option B)

Event #3 is the refund signal. In a native Stripe integration, price would be -179.99. With the External API, the price is always 0.00. Revenue IS correctly adjusted inside RC — query the Subscriber API to confirm net revenue.

Cancel Immediately + Prorated Refund (Option C)

No CANCELLATION (CUSTOMER_SUPPORT) event is generated for prorated refunds. The refund is invisible in webhooks. Revenue is adjusted internally in RC. Use the Flex API or RC Subscriber API for refund details.

Subscription Expires Naturally (After Cancel at Period End)

This fires when the billing period ends after a CancelAtPeriodEnd was set.

Field Reference

Every RC webhook event from Flex will have these field values:

Key Differences from Stripe-Native Integration

If your webhook consumer was originally built for a native Stripe → RevenueCat integration, the following differences apply when receiving events from Flex. These are inherent to the RevenueCat External Purchases API and have been confirmed with the RevenueCat team (March 2026).

These differences are not bugs. They are confirmed RevenueCat platform behavior for the External Purchases API. Flex sends all available data correctly; the External API simply exposes different fields than native integrations.

Refund Handling

Refund visibility in RC webhooks depends on the refund type and flow:

How to detect and measure refunds

Recommended: Use Flex webhooks for refund tracking (exact amounts and types) and RC webhooks for subscription lifecycle (active, canceled, expired, billing).

Recommendations for Webhook Consumers

Handling the store field

Accept events where store is either "STRIPE" or "EXTERNAL":

if event.store in ["STRIPE", "EXTERNAL"]:
    process_event(event)

Detecting subscription state changes

Use the event type and cancel_reason to determine subscription state:

Handling refunds

1. Detect refund occurrence
   Check for cancel_reason == "CUSTOMER_SUPPORT" on CANCELLATION events.
2. Do NOT rely on negative price
   The price will always be 0.0 for External store events.
3. Get refund amounts
   Use the Flex API or RC Subscriber API for exact refund amounts.
4. Handle prorated/custom refunds
   No RC webhook event is generated for these — use Flex webhooks instead.

Handling expiration events

Accept expiration_reason: null. The External store does not populate this field. To determine why a subscription expired, look at the preceding CANCELLATION event’s cancel_reason.

ID formats

Treat all IDs as opaque strings. Do not parse, validate format, or assume a prefix:

Example Payloads

All payloads below are from real webhook captures in the RevenueCat sandbox.

• INITIAL_PURCHASE (Trial Start)
• INITIAL_PURCHASE (Conversion)
• RENEWAL
• CANCELLATION (User)
• CANCELLATION (Refund)
• UNCANCELLATION
• EXPIRATION
• BILLING_ISSUE

{
  "api_version": "1.0",
  "event": {
    "type": "INITIAL_PURCHASE",
    "store": "EXTERNAL",
    "environment": "SANDBOX",
    "product_id": "fprod_xxx",
    "transaction_id": "fsub_xxx",
    "original_transaction_id": "fsub_xxx",
    "app_user_id": "fcus_xxx",
    "currency": "USD",
    "price": 0.0,
    "price_in_purchased_currency": 0.0,
    "period_type": "NORMAL",
    "renewal_number": 1,
    "is_family_share": false,
    "commission_percentage": 0.0,
    "takehome_percentage": 1.0,
    "tax_percentage": 0.0,
    "country_code": null,
    "entitlement_ids": null,
    "expiration_reason": null,
    "cancel_reason": null,
    "subscriber_attributes": {}
  }
}

{
  "api_version": "1.0",
  "event": {
    "type": "INITIAL_PURCHASE",
    "store": "EXTERNAL",
    "environment": "SANDBOX",
    "product_id": "fprod_xxx",
    "transaction_id": "fsub_xxx",
    "app_user_id": "fcus_xxx",
    "currency": "USD",
    "price": 179.99,
    "price_in_purchased_currency": 179.99,
    "commission_percentage": 0.0,
    "takehome_percentage": 1.0,
    "tax_percentage": 0.0,
    "renewal_number": 1
  }
}

{
  "api_version": "1.0",
  "event": {
    "type": "RENEWAL",
    "store": "EXTERNAL",
    "product_id": "fprod_xxx",
    "app_user_id": "fcus_xxx",
    "currency": "USD",
    "price": 179.99,
    "price_in_purchased_currency": 179.99,
    "commission_percentage": 0.0,
    "takehome_percentage": 1.0,
    "renewal_number": 1
  }
}

{
  "api_version": "1.0",
  "event": {
    "type": "CANCELLATION",
    "cancel_reason": "UNSUBSCRIBE",
    "store": "EXTERNAL",
    "product_id": "fprod_xxx",
    "app_user_id": "fcus_xxx",
    "currency": "USD",
    "price": 0.0,
    "price_in_purchased_currency": 0.0,
    "commission_percentage": 0.0,
    "takehome_percentage": 1.0
  }
}

{
  "api_version": "1.0",
  "event": {
    "type": "CANCELLATION",
    "cancel_reason": "CUSTOMER_SUPPORT",
    "store": "EXTERNAL",
    "product_id": "fprod_xxx",
    "app_user_id": "fcus_xxx",
    "currency": "USD",
    "price": 0.0,
    "price_in_purchased_currency": 0.0,
    "commission_percentage": 0.0,
    "takehome_percentage": 1.0
  }
}

Price is 0.0, not negative. Revenue is adjusted inside RC but not reflected in this webhook payload.

{
  "api_version": "1.0",
  "event": {
    "type": "UNCANCELLATION",
    "store": "EXTERNAL",
    "product_id": "fprod_xxx",
    "app_user_id": "fcus_xxx",
    "currency": "USD",
    "price": 0.0,
    "commission_percentage": 0.0,
    "takehome_percentage": 1.0
  }
}

{
  "api_version": "1.0",
  "event": {
    "type": "EXPIRATION",
    "expiration_reason": null,
    "store": "EXTERNAL",
    "product_id": "fprod_xxx",
    "app_user_id": "fcus_xxx",
    "currency": "USD",
    "price": 0.0,
    "price_in_purchased_currency": 0.0,
    "commission_percentage": 0.0,
    "takehome_percentage": 1.0
  }
}

{
  "api_version": "1.0",
  "event": {
    "type": "BILLING_ISSUE",
    "store": "EXTERNAL",
    "product_id": "fprod_xxx",
    "app_user_id": "fcus_xxx",
    "currency": "USD",
    "price": 0.0,
    "commission_percentage": 0.0,
    "takehome_percentage": 1.0
  }
}