RevenueCat Web Billing

Track commission on web subscriptions using RevenueCat's Web SDK with Web Billing - managing subscriptions directly through RevenueCat's web platform.

When you enable RevenueCat Web Billing tracking, you can attribute web subscriptions to affiliates by passing UTM parameters as purchase metadata.

What You Can Track

Once configured, Insert Affiliate automatically tracks:

  • RevenueCat web subscriptions made through the Web SDK
  • Initial subscription purchases
  • Subscription renewals
  • All transactions managed by RevenueCat's web billing system

Prerequisites

Before setting up Insert Affiliate tracking, you must have:

  • RevenueCat Web SDK installed and configured
  • RevenueCat Web Billing set up with Stripe
  • Insert Affiliate SDK initialized on your page
  • Stripe Connect configured in your Insert Affiliate dashboard

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 1 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: Connect Your Stripe Account via Stripe Connect

Since RevenueCat Web Billing uses Stripe under the hood, you need to connect your Stripe account to Insert Affiliate:

  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 Stripe events from RevenueCat transactions.

Implementation: SDK Integration

Step 1: Install the Insert Affiliate SDK

Add the Insert Affiliate SDK to your web application:

npm install insert-affiliate-js-sdk

Step 2: Initialize Both SDKs

Initialize both the Insert Affiliate SDK and RevenueCat Web SDK:

import { InsertAffiliate } from 'insert-affiliate-js-sdk';
import { Purchases } from '@revenuecat/purchases-js';

// Initialize Insert Affiliate SDK
await InsertAffiliate.initialize('your_company_code');

// Initialize RevenueCat Web SDK
const purchases = Purchases.configure('your_revenuecat_web_api_key');

Step 3: Pass Affiliate Data During Purchase

Before making a purchase, retrieve the affiliate identifier and company ID, then pass them as UTM parameters in the purchase metadata:

// Get the current affiliate identifier and company ID
// Use ignoreTimeout: true to get the identifier even if attribution window expired
const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier(true);
const companyId = await InsertAffiliate.returnCompanyId();

console.log('Affiliate ID:', affiliateId || 'none');
console.log('Company ID:', companyId || 'none');

// Prepare metadata with UTM parameters for RevenueCat Web Billing
const metadata: Record<string, string> = {};

if (affiliateId && affiliateId !== 'none') {
  metadata.utm_source = 'insertAffiliate';
  metadata.utm_medium = companyId || 'none';
  metadata.utm_campaign = affiliateId;
}

console.log('Purchase metadata:', JSON.stringify(metadata, null, 2));

// Get offerings and select a package
const offerings = await purchases.getOfferings();
const selectedPackage = offerings.current?.availablePackages[0];

if (!selectedPackage) {
  console.error('No packages available');
  return;
}

// Make the purchase with metadata
const { customerInfo } = await purchases.purchase({
  rcPackage: selectedPackage,
  metadata: metadata,
});

console.log('Purchase successful!');
console.log('Active entitlements:', Object.keys(customerInfo.entitlements.active));

Required UTM Parameters

The following UTM parameters are required for proper affiliate attribution:

  • utm_source: Always set to 'insertAffiliate' to identify Insert Affiliate conversions
  • utm_medium: Your Insert Affiliate company ID
  • utm_campaign: The affiliate's identifier (short code)

Important Notes:

  • Always call returnInsertAffiliateIdentifier() and returnCompanyId() before initiating the purchase
  • Only include UTM parameters in metadata if an affiliate identifier exists
  • The metadata will be sent with the purchase and available in RevenueCat webhook events

If you're using RevenueCat Web Purchase Links for online campaigns (such as email marketing, social media, or affiliate promotions), you must append UTM parameters to ensure proper affiliate tracking.

Important: This also applies if you're using RevenueCat Paywalls in your mobile app with an app-to-web flow. RevenueCat's native Paywalls feature does not support passing custom metadata on mobile platforms, so you must use one of these approaches:

  1. Redirect to Web Purchase Links - Instead of using RevenueCat's Paywall UI, direct users to a Web Purchase Link with UTM parameters appended (recommended approach)
  2. Build a Custom Paywall - Create your own paywall UI that fetches offerings and calls the purchase method with metadata directly

How It Works

RevenueCat Web Purchase Links are hosted payment pages that allow you to sell subscriptions without building your own checkout flow. To track affiliate attribution, append UTM parameters to these links.

Required UTM Parameters

  • utm_source: Always set to insertAffiliate
  • utm_medium: Your Insert Affiliate company ID
  • utm_campaign: The affiliate's short code

Example

If your RevenueCat Web Purchase Link is:

https://pay.rev.cat/sandbox/viqxbcoudyfaeaae/

You should append the UTM parameters:

?utm_source=insertAffiliate&utm_medium={insertAffiliateCompanyId}&utm_campaign={affiliateShortCode}

Full Example With Parameters

https://pay.rev.cat/sandbox/viqxbcoudyfaeaxa/?utm_source=insertAffiliate&utm_medium=12345&utm_campaign=AFF123

Where:

  • utm_source=insertAffiliate - Identifies this as an Insert Affiliate conversion
  • utm_medium=12345 - Your unique Insert Affiliate company ID
  • utm_campaign=AFF123 - The affiliate's short code

How to Get Your Company ID

You can find your Insert Affiliate company ID in your dashboard settings.

How to Get the Affiliate Identifier

The affiliate identifier (short code) 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 →

Deep Linking Platforms

Can I Use RevenueCat Web Purchase Links?

Whilst it is possible to use RevenueCat Web Purchase Links as the deep link you provide to your affiliates, we do not recommend this as doing so will cause ONLY web-based transactions to be tracked—not in-app purchases.

This limitation exists due to how RevenueCat payment links handle the passing of utm_source, utm_medium, and utm_campaign parameters into the app upon claiming via RevenueCat redemption links.

Recommended Approach:

If you want to use RevenueCat Web Purchase Links for your affiliates, you should:

  1. Select "RevenueCat Web Purchase Links" in your Insert Affiliate settings to track web-based sales
  2. Implement short codes as a fallback mechanism within your mobile app
  3. Prompt users within your app to identify which affiliate recommended them
  4. Apply affiliate attribution for future in-app purchases based on their response

This hybrid approach ensures comprehensive tracking across both web purchases (via UTM parameters in the Web Purchase Link) and in-app purchases (via short codes).

When to Use This Approach:

Only use RevenueCat Web Purchase Links as your deep linking platform if you are comfortable with the limitation that redemption links will not automatically attribute in-app purchases to affiliates. The short code fallback is essential for maintaining proper attribution for mobile transactions.

Testing Your Setup

Testing SDK Integration

  1. Connect your Stripe account via Stripe Connect
  2. Initialize the Insert Affiliate SDK on your page
  3. Initialize the RevenueCat Web SDK
  4. Make a test purchase with UTM parameters in the metadata
  5. Check your transactions dashboard to confirm the transaction appears

Testing Web Purchase Links

  1. Create a RevenueCat Web Purchase Link
  2. Append the required UTM parameters (utm_source, utm_medium, utm_campaign)
  3. Click the link and complete a test purchase
  4. Check your transactions dashboard to verify the transaction is attributed

Troubleshooting

Transactions Not Showing Up

Check these common issues:

  • Stripe Connect status: Verify your Stripe account shows as "Active" in settings
  • UTM parameters: Confirm you're passing all three required UTM parameters (utm_source, utm_medium, utm_campaign)
  • SDK initialization: Ensure the Insert Affiliate SDK is properly initialized and returning valid values
  • RevenueCat Stripe connection: Verify RevenueCat Web Billing is properly connected to the same Stripe account you connected via Stripe Connect
  • Metadata format: Check that UTM parameters are being passed correctly in the purchase metadata

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 initiate purchases
  • Attribution window: Verify the affiliate identifier hasn't expired (use ignoreTimeout: true if needed)

Web Purchase Links Not Tracking

  • UTM parameter format: Ensure UTM parameters are properly URL-encoded
  • Parameter spelling: Double-check that parameter names are spelled correctly (utm_source, utm_medium, utm_campaign)
  • Company ID: Verify you're using the correct Insert Affiliate company ID
  • Affiliate short code: Confirm the affiliate short code is valid and active

What Happens Next

Once configured:

  1. Purchases with UTM 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 handles subscription management while Insert Affiliate tracks attribution