RevenueCat Stripe Billing

Track commission on web subscriptions managed by RevenueCat's Stripe Billing integration - combining RevenueCat's subscription management with Stripe's payment processing.

When you enable RevenueCat Stripe Billing tracking, you can attribute web subscriptions to affiliates while RevenueCat handles subscription lifecycle management.

What You Can Track

Once configured, Insert Affiliate automatically tracks:

  • RevenueCat web subscriptions processed through Stripe
  • Initial subscription purchases
  • Subscription renewals
  • All transactions managed by RevenueCat's web billing

Prerequisites

Before setting up Insert Affiliate tracking, you must have:

  • RevenueCat Web SDK installed and configured
  • RevenueCat Stripe Billing set up and connected to your Stripe account
  • Your own hosted checkout page where the Insert Affiliate SDK can run
  • A Stripe account ready to connect via Stripe Connect

Important: Insert Affiliate requires your checkout to be hosted on your own domain. The SDK must run on your page to capture affiliate attribution before purchases.

RevenueCat Webhook Configuration

Important: When configuring your RevenueCat webhook to send events to Insert Affiliate, you should only send App Store and Google Play Store events - not Stripe or Web Billing events.

Since Insert Affiliate receives Stripe events directly through Stripe Connect (configured in Step 2 below), sending RevenueCat webhook events for Stripe/Web Billing transactions would result in duplicate transaction tracking.

To configure your RevenueCat webhook:

  1. Go to your RevenueCat dashboard → Project Settings → Integrations → Webhooks
  2. When setting up the Insert Affiliate webhook, configure it to only send events for:
    • App Store (iOS)
    • Google Play Store (Android)
  3. Do not include Stripe or Web Billing events in this webhook

This ensures clean attribution: mobile transactions are tracked via RevenueCat webhooks, while web transactions are tracked via Stripe Connect.

Setup Guide

Step 1: Enable Web Payments

  1. Go to Settings → Web Transactions
  2. Change Web Transaction Method from "Disabled" to "Stripe Web Payments"
  3. Click "Save Settings"

Step 2: Set Up Stripe Connect

Before you can track web transactions, you must connect your Stripe account:

  1. Go to Settings → Stripe Connect
  2. Click "Connect with Stripe"
  3. Complete the Stripe onboarding process:
    • Log in to your existing Stripe account (the same one connected to RevenueCat)
    • Provide required business information
    • Submit verification documents (if requested)
  4. You'll be redirected back to Insert Affiliate once complete

Status indicators:

  • Active: Your Stripe account is fully connected and ready
  • Restricted: Additional information needed - click "Continue Onboarding"
  • Pending: Documents under review (usually 1-2 business days)

✅ Once your Stripe account is connected, Insert Affiliate will automatically receive all Stripe events from your RevenueCat transactions.

Implementation: Passing Affiliate Codes

Step 1: Install the Insert Affiliate SDK

Add the Insert Affiliate SDK to your web checkout page:

npm install insert-affiliate-js-sdk

Step 2: Initialize the SDK

Initialize the SDK on your checkout page before users complete purchases:

import { InsertAffiliate } from 'insert-affiliate-js-sdk';

// Initialize SDK with your company code
await InsertAffiliate.initialize('your_company_code');

Step 3: Pass Affiliate Data to Stripe Checkout

When creating a Stripe Checkout session, include both required fields in all three metadata locations to ensure proper tracking:

// Get the current affiliate identifier and company ID
const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
const companyId = await InsertAffiliate.returnCompanyId();

// Create Stripe checkout session with metadata
const session = await stripe.checkout.sessions.create({
  line_items: [
    {
      price: 'price_1234',
      quantity: 1,
    },
  ],
  mode: 'subscription',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  // 1. Session metadata (available in checkout.session.completed event)
  metadata: {
    insertAffiliate: affiliateId || '',
    insertAffiliateCompanyId: companyId || '',
  },
  // 2. Subscription metadata (persists with subscription)
  subscription_data: {
    metadata: {
      insertAffiliate: affiliateId || '',
      insertAffiliateCompanyId: companyId || '',
    },
  },
  // 3. Payment Intent metadata (available on each payment)
  payment_intent_data: {
    metadata: {
      insertAffiliate: affiliateId || '',
      insertAffiliateCompanyId: companyId || '',
    },
  },
});

Required Metadata Fields

Both of the following fields are required for proper affiliate attribution:

  • insertAffiliate - The affiliate's short code (identifier)
  • insertAffiliateCompanyId - Your Insert Affiliate company ID

These fields must be passed in all three metadata locations (session, subscription, and payment intent) to ensure Insert Affiliate can properly track and attribute payments.

How It Works Together

  1. RevenueCat manages the subscription lifecycle (trials, renewals, cancellations)
  2. Stripe processes the actual payments
  3. Insert Affiliate tracks affiliate attribution through Stripe metadata
  4. Your hosted checkout runs the Insert Affiliate SDK to capture attribution

Since you connected your Stripe account via Stripe Connect (Step 2), Insert Affiliate automatically receives all Stripe events - including those from RevenueCat subscriptions - and reads the metadata fields to credit affiliates.

How to Get the Required Values

You need to retrieve both values from the Insert Affiliate SDK. The SDK automatically handles deep link detection and affiliate attribution.

Getting the Affiliate Identifier

The affiliate identifier can come from multiple sources:

  • Deep linking: When a user clicks an affiliate link, capture the identifier through your deep linking platform
  • Short code: Users can manually enter or apply an affiliate short code
  • URL parameters: Automatically detected by the SDK

View JS SDK documentation →

Getting the Company ID

Your Insert Affiliate company ID is also required.

View JS SDK documentation →

Passing to Your Backend

Send both values to your backend when creating checkout sessions:

const response = await fetch('/create-checkout-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_1234',
    insertAffiliate: affiliateId,
    insertAffiliateCompanyId: companyId,
    successUrl: window.location.origin + '/success',
    cancelUrl: window.location.origin + '/cancel',
  }),
});

Testing Your Setup

  1. Enable Stripe Web Payments in your settings
  2. Connect your Stripe account via Stripe Connect
  3. Initialize the Insert Affiliate SDK on your checkout page
  4. Make a test purchase with both required fields (insertAffiliate and insertAffiliateCompanyId) in the metadata
  5. Check your transactions dashboard to confirm the transaction appears

Troubleshooting

Transactions Not Showing Up

Check these common issues:

  • Stripe Connect status: Verify your Stripe account shows as "Active" in settings
  • Web Payments enabled: Confirm "Stripe Web Payments" is selected in settings
  • Required metadata fields: Confirm you're passing both insertAffiliate and insertAffiliateCompanyId in all three metadata locations (session, subscription_data, payment_intent_data)
  • SDK initialization: Ensure the Insert Affiliate SDK is properly initialized on your checkout page and returning valid values
  • RevenueCat Stripe connection: Verify RevenueCat is properly connected to the same Stripe account you connected via Stripe Connect
  • Hosted checkout: Confirm the Insert Affiliate SDK is running on your own hosted checkout page (not a third-party hosted page)

SDK Not Detecting Affiliate

  • Deep link setup: Verify your deep linking platform is properly configured
  • URL parameters: Check that affiliate links include the proper insertAffiliate parameter
  • SDK initialization timing: Ensure the SDK is initialized before users land on your checkout page

What Happens Next

Once configured:

  1. Purchases with affiliate metadata automatically create commission records
  2. View all transactions in your dashboard
  3. Configure commission rates per affiliate
  4. Set up payment methods to pay your affiliates
  5. RevenueCat continues to handle subscription management while Insert Affiliate tracks attribution