RevenueCat

Requirements

To set up RevenueCat for your Floot app, you will need:

• A RevenueCat account.
• An App Store Connect account, for iOS and macOS.
• A Google Play Console account, for Android.
• A real device. Simulators and emulators do not support the full in-app purchase flow; see Sandbox testing.

Setup

Turn RevenueCat on

RevenueCat ships disabled. The SDK is never configured and the Edge Functions never call RevenueCat's API until you say so, so a project that monetizes purely through Stripe, or not at all, can leave this alone.

ENABLE_REVENUECAT=true

ENABLE_REVENUECAT=true

SDK keys

Go to RC dashboard → your project → API keys (sidebar).

• Under SDK API keys, copy the Public API key of each app config and paste it into the app's .env.local.
• Under Secret API keys, create a key with read and write access to subscribers and paste it into supabase/.env.local.

REVENUECAT_PUBLIC_APPLE_KEY="appl_..."
REVENUECAT_PUBLIC_ANDROID_KEY="goog_..."

REVENUECAT_SECRET_API_KEY="<your_revenuecat_secret_api_key>"

Restore behaviour

In RC dashboard → your project → Project settings → General, set Restore behavior to Transfer to new App User ID.

Both settings work: the app handles the resulting TRANSFER webhook and reconciles either way. But "Transfer" is the one that makes a Restore purchases tap from a different account do the intuitive thing: move the purchase to the account that is asking for it.

Store setup

Your store is where products and prices actually live; RevenueCat imports them. Both stores have their own well-maintained guides, so this section only covers what is specific to your project.

Entitlements and offerings

RevenueCat groups store products into entitlements (what the user gets) and offerings (what you show them).

Source: RC Entitlements.

Plans and prices

Unlike Stripe, RevenueCat does not sync its catalog into your database. The paywall reads plans and prices from Supabase, so you mirror your RevenueCat catalog there by hand, once.

INSERT INTO
    plans (id, name, provider, description, platform, active)
VALUES
    ('entlxxx123', 'Basic', 'revenuecat', 'Perfect for getting started.', 'android', TRUE),
    ('entlxxx321', 'Premium', 'revenuecat', 'Unlock everything.', 'apple', TRUE);

INSERT INTO
    prices (id, plan_id, amount, currency, interval, type, active)
VALUES
    ('myapp_999_1m_00', 'entlxxx123', 9.99, 'usd', 'monthly', 'recurring', TRUE),
    ('myapp_9999_1y_00', 'entlxxx123', 99.99, 'usd', 'yearly', 'recurring', TRUE),
    ('myapp_2999_1m_00', 'entlxxx321', 29.99, 'usd', 'monthly', 'recurring', TRUE),
    ('myapp_29999_1y_00', 'entlxxx321', 299.99, 'usd', 'yearly', 'recurring', TRUE);

Webhooks

RevenueCat is the source of truth for entitlements; the subscriptions table is a replica of it. Webhook events keep the replica current, and the integration does not grant access without them: a completed purchase never unlocks anything.

Eleven event types are handled:

Anything else is acknowledged and ignored, not rejected, so leaving the dashboard on All events is harmless, just noisier. A payload that cannot be parsed at all is acknowledged and dropped rather than left to burn through RevenueCat's five retries.

Create the webhook

Go to RC dashboard → Integrations (sidebar) → Webhooks (under RevenueCat core tools) → Add new configuration.

• Name: anything; it only distinguishes multiple endpoints.
• Webhook URL: see the tabs below.

<generated.forward.address>/functions/v1/revenuecat-webhook

• Authorization header value: mandatory, and the handler compares it against REVENUECAT_WEBHOOK_SECRET byte for byte.

Bearer <generated_key>

REVENUECAT_WEBHOOK_SECRET="dXNlcm5hbWU6cGFzc3dvcmQ="

• Environment to send events for: production, sandbox, or both.
• Apps / Event type (under Events filter): All apps and All events are fine.

→ Add webhook (lower right)

Source: RC Webhooks.

Restore purchases

Store purchases outlive an account: a user reinstalls, signs in on a new phone, or creates a second account against the same Apple ID. Both stores require an app that sells non-consumables or subscriptions to offer a way to recover them.

It is offered in three places, and only when context.canRestorePurchases is true:

bool get canRestorePurchases => Env.ENABLE_REVENUECAT && supportsIAP;

Stripe subscriptions have no store receipt, so the action stays hidden wherever purchases are not made through a store.

The first two show a confirmation dialog first, because restoring is not free of consequence: it moves the purchase, unlinking it from any other account it is currently attached to.

Every entry point runs the same two steps:

The function answers with one of five outcomes, and the UI shows honest copy for each rather than a blanket success/failure toast:

Only three conditions are real errors: NOT_AUTHENTICATED, RC_UNAVAILABLE (RevenueCat unreachable, the user may retry) and PLAN_NOT_CONFIGURED (the entitlement/product pair has no matching row; see Plans and prices). Failures get their own copy too, so a restore that cannot run never looks like a restore that found nothing.

Which paywall renders

Two paywalls ship. Which one a user sees is decided by context.canShowRevenueCatPaywall:

bool get canShowRevenueCatPaywall =>
    isMobile &&
    Env.ENABLE_REVENUECAT &&
    !Env.ENABLE_STRIPE_MOBILE &&
    Env.ENABLE_REVENUECAT_PAYWALL;

All four conditions must hold. In particular:

• isMobile is iOS and Android only; macOS always gets the built-in paywall, even with ENABLE_IAP_MACOS on.
• Turning on ENABLE_STRIPE_MOBILE takes precedence and returns mobile to Stripe.

ENABLE_REVENUECAT_PAYWALL=true

RevenueCat's Paywalls let you change the whole purchase screen from the dashboard, with no code change and no app update.

Customizing the built-in paywall (plan descriptions, feature lists, lifetime prices, or removing the paywall altogether) is covered on the App Paywall page.

Handling business logic

Floot provides sensible defaults for subscriptions and one-time payments, but you can extend the handlers to fit your business.

Subscriptions

Subscription access is managed automatically from the entitlement the user bought. Extra logic, awarding credits, coins, or anything else, belongs in supabase/functions/revenuecat-webhook/_events/rc_sub_handlers.ts.

One time payments

To handle one-time payments (non-renewing purchases), edit supabase/functions/revenuecat-webhook/_events/non_renewing_purchase.ts and follow the comments starting with // ! ....

Free trials

Trials are configured in the store, not in RevenueCat and not in your database. On Apple they are introductory offers; on Google Play they are offers on a base plan.

Two things are RevenueCat-specific and easy to miss:

• The store grants the trial; your database only advertises it. A trial you configure in the store applies at purchase whether or not your database knows about it; the user simply is not told. To show it on the built-in paywall, set trial_days on the matching prices row yourself. (RevenueCat's own paywall reads the offer from the store and needs nothing.)
• Trials cannot be offered on one-time purchases; the prices table enforces that with a check constraint.

UPDATE prices
SET trial_days = 7
WHERE id = '<your_price_id>';

Everything after that (eligibility, the paywall badge, the trial-ending notification schedule, and how to let a user trial more than once) is provider-agnostic and lives on the Free Trials page.

In-app purchases on macOS

The RevenueCat SDK is configured on macOS as well as iOS and Android, but the in-app purchase surfaces stay hidden until you opt in: a macOS build distributed outside the App Store has no store to buy from.

ENABLE_IAP_MACOS=true

Remember to add the In-App Purchase capability to the macos Runner target in Xcode, exactly as for iOS.

Sandbox testing

You don't need to make real purchases to test your subscriptions. The store sandboxes behave like the real thing without charging anyone.

If you point a sandbox webhook at a locally forwarded URL, remember the webhook still has to reach revenuecat-webhook; serve the functions with:

supabase functions serve --env-file .env.local --import-map ./functions/deno.json --no-verify-jwt

Source: RC Sandbox Testing.