Revenuecat

You are required to ensure these requirements are met before setting up or using RevenueCat.

Project Structure

• Scripts directory: scripts/ at the workspace root (e.g., scripts/seedRevenueCat.ts)
• Run a script: npx tsx scripts/<script>.ts
• Client app directory: client/

Reference files use these terms. Map them to these concrete paths.

Essential Clarifications -- Critical

• RevenueCat DOES work in Expo Go and DOES NOT require a native build. In Expo Go, the SDK automatically runs in Preview API Mode, replacing native calls with JavaScript mocks so your app loads without errors.
• RevenueCat DOES work on the web out of the box without any additional configuration.
• RevenueCat's Test Store DOES work out of the box and DOES NOT require additional code checks.

RevenueCat Architecture

• Projects: A RevenueCat project is the top-level entity for RevenueCat - it's like a container for your apps, products, entitlements, and integrations.
  • Each project comes with a Test Store where you can create products, configure offerings, and test the complete purchase flow—without connecting to any app store or payment provider.
• Apps: An app in RevenueCat is a platform-specific configuration that connects your project to a store (e.g., an iOS app connected to Apple App Store, an Android app connected to Google Play Store, or a web app connected to Stripe/Paddle).
• Products: The individual items users purchase (e.g., "Monthly Premium")
• Entitlements: The access level users receive (e.g., "premium"). Most apps use a single entitlement (e.g., "pro"). They are linked to products: when a product is purchased, its associated entitlements become active.
  • The flow: User purchases a Product -> which then unlocks an Entitlement -> You check the entitlement to grant access.
• Offerings: The set of products available to a user. Allow you to change available products without app updates. Access via offerings.current on the client for the default offering.
  • The client side code always queries the current offering as a source of truth to get the products and packages available to the user. Therefore, it is critical that this be always up to date.
• Packages: Containers for products within an offering.
• CustomerInfo: The central object containing all subscription and purchase data for a user

Storing Data

Do NOT Create Product Tables or Maintain Any Other Source of Truth for In-App Purchases

Bad — creates duplicate product storage:

export const products = pgTable("products", {
  id: varchar("id").primaryKey(),
  name: text("name"),
  price: integer("price"),
  // ... custom fields
});

Correct Approach:

• NO product tables needed!
• Query directly from RevenueCat SDK

Key Principle "If it exists in RevenueCat, it belongs in RevenueCat"

• Don't duplicate RevenueCat data in your own tables.
• Don't create parallel storage systems.
• RevenueCat + metadata = your complete product catalog.
• Your tables should only store data that RevenueCat doesn't manage.

Free Trials

• Free trials are not supported in the test store due to a RevenueCat limitation.
• Free trials can be configured directly in App Store Connect and the Google Play Console.
• If a user asks about adding free trials:
  • Inform them of this limitation and note that the client can automatically detect and display free trials via RevenueCat once enabled in production.
  • RevenueCat reads store product metadata, including trial details, in the package object.

Working with Prices

• Never hardcode prices in the client code; always derive them from the subscription context.
• Prices in the test store are immutable; production store prices are configured in App Store Connect and the Google Play Console.

References

Before writing code, identify whether any reference below applies to the task. If it does, read it first.

• ./references/initial-setup.md -- Step-by-step guide for setting up RevenueCat from scratch in a project that doesn't already have it configured
• ./references/replit-revenuecat-v2-docs.md -- SDK Reference for the replit-revenuecat-v2 package
• ./references/subsequent-management.md -- Querying RevenueCat data (e.g. fetching customers, entitlements) and managing resources (creating, updating, deleting products, offerings, prices, etc.) after initial setup