Revenuecat

Documentation from ramonclaudio/convex-revenuecat, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

What This Component Does

This component receives RevenueCat webhooks and maintains subscription state in your Convex database. Use it to:

• Check if users have active entitlements (e.g., "premium" access)
• Query subscription status with Convex's real-time reactivity

Copy codegraph LR
    A[RevenueCat] -->|webhooks| B[Component]
    B -->|writes| C[(Convex DB)]
    C -->|queries| D[Your App]

This is not a replacement for the RevenueCat SDK. Use their SDK in your client app for purchases. This component handles the server-side state that webhooks provide.

[!TIP] Webhook timing: After a purchase completes in the SDK, there's a delay before RevenueCat sends the webhook (usually seconds, occasionally longer). During this window, hasEntitlement() returns false. Once the webhook arrives, Convex's real-time sync updates your UI. No polling needed.

Features

• Webhook Processing: Idempotent handling of all 18 RevenueCat webhook events
• Convex Integration: Data stored in Convex tables with real-time reactivity
• Correct Edge Cases: Cancellation keeps access until expiration, pause doesn't revoke, etc.
• Rate Limiting: Built-in protection against webhook abuse (100 req/min per app)
• Subscriber Attributes: Stores customer attributes from webhooks
• Experiment Tracking: Tracks A/B test enrollments
• TypeScript: Typed API methods (webhook payloads stored as-is)

Prerequisites

• Convex project (v1.31.6 or later)
• RevenueCat account with webhook access

Installation

Copy codenpm install convex-revenuecat

Quick Start

1. Configure the Component

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import revenuecat from "convex-revenuecat/convex.config";

const app = defineApp();
app.use(revenuecat);

export default app;

2. Mount the Webhook Handler

Copy code// convex/http.ts
import { httpRouter } from "convex/server";
import { RevenueCat } from "convex-revenuecat";
import { components } from "./_generated/api";

const http = httpRouter();

const revenuecat = new RevenueCat(components.revenuecat, {
  REVENUECAT_WEBHOOK_AUTH: process.env.REVENUECAT_WEBHOOK_AUTH,
});

http.route({
  path: "/webhooks/revenuecat",
  method: "POST",
  handler: revenuecat.httpHandler(),
});

export default http;

3. Set Up Environment Variables

Generate a secure random string for webhook authorization:

Copy codeopenssl rand -base64 32

Add it to your Convex deployment:

Copy codenpx convex env set REVENUECAT_WEBHOOK_AUTH "your-generated-secret"

For local development, add to your .env.local file instead.

4. Configure RevenueCat Webhooks

1. Open the RevenueCat Dashboard
2. Select your project
3. Go to Project Settings → Integrations → Webhooks
4. Click + New
5. Configure the webhook:

6. Click Save

Find your Convex deployment URL in the Convex Dashboard under your project's Settings → URL & Deploy Key.

5. Test the Webhook

1. In RevenueCat, go to your webhook configuration
2. Click Send Test Event
3. Verify the event was received:

Copy codenpx convex logs

You should see a log entry showing the TEST event was processed.

If the test fails, check Troubleshooting below.

Usage

Check Entitlements

Copy codeimport { query } from "./_generated/server";
import { components } from "./_generated/api";
import { RevenueCat } from "convex-revenuecat";
import { v } from "convex/values";

const revenuecat = new RevenueCat(components.revenuecat);

export const checkPremium = query({
  args: { appUserId: v.string() },
  returns: v.boolean(),
  handler: async (ctx, args) => {
    return await revenuecat.hasEntitlement(ctx, {
      appUserId: args.appUserId,
      entitlementId: "premium",
    });
  },
});

Get Active Subscriptions

Copy codeexport const getSubscriptions = query({
  args: { appUserId: v.string() },
  handler: async (ctx, args) => {
    return await revenuecat.getActiveSubscriptions(ctx, {
      appUserId: args.appUserId,
    });
  },
});

Centralizing Access

Create a module to avoid instantiating RevenueCat in every file:

Copy code// convex/revenuecat.ts
import { RevenueCat } from "convex-revenuecat";
import { components } from "./_generated/api";

export const revenuecat = new RevenueCat(components.revenuecat, {
  REVENUECAT_WEBHOOK_AUTH: process.env.REVENUECAT_WEBHOOK_AUTH,
});

[!IMPORTANT] ID matching is critical:

• The app_user_id you pass to Purchases.logIn() must match what you query with hasEntitlement(). Use a consistent identifier (e.g., your Convex user ID).
• The entitlementId parameter (e.g., "premium") must match exactly what you configured in the RevenueCat dashboard.

API Reference

Query Behavior

• Missing users: Queries return empty arrays or null (never throw). Use this for loading states.
• Billing issues: During grace periods, hasEntitlement() returns true and getActiveSubscriptions() includes the subscription.
• Lifetime purchases: Subscriptions without expirationAtMs are always considered active.

Constructor

Copy codeconst revenuecat = new RevenueCat(components.revenuecat, {
  REVENUECAT_WEBHOOK_AUTH?: string, // Webhook authorization header
});

Query Methods

This component is a read-only sync layer. To grant promotional entitlements, use the RevenueCat API directly — the webhook will sync the state automatically.

Webhook Events

[!IMPORTANT] CANCELLATION does not revoke entitlements. Users keep access until EXPIRATION.

Database Schema

The component creates ten tables:

Limitations

• No initial sync — Existing subscribers before webhook setup won't appear until they trigger a new event (renewal, cancellation, etc.)
• Webhook-driven only — Data comes exclusively from webhooks; no API polling or backfill mechanism
• Raw payload storage — Webhook payloads are stored as-is for debugging. These may contain subscriber attributes or other data you've configured in RevenueCat. Events are auto-deleted after 30 days.
• Production usage — Core entitlement checking (hasEntitlement) is production-tested. Other query methods (transfers, invoices, virtual currency) are unit-tested but not yet battle-tested in production apps.

Testing

Register the component in your tests:

Copy codeimport { convexTest } from "convex-test";
import revenuecatTest from "convex-revenuecat/test";

function initConvexTest() {
  const t = convexTest();
  revenuecatTest.register(t);
  return t;
}

test("check premium access", async () => {
  const t = initConvexTest();
  // Your test code here
});

Example

See the example/ directory for a complete working example with:

• Component registration
• Webhook handler setup
• Query and mutation examples

Troubleshooting

The authorization header doesn't match.

1. Verify the environment variable is set:

   Copy codenpx convex env get REVENUECAT_WEBHOOK_AUTH
   

2. Ensure the value in RevenueC

[README truncated for prompt length]