Use this skill to orient an agent to the RevenueCat Android SDK (10.x) architecture. Covers how RevenueCat reorganizes BillingClient, Google Play Developer API, and RTDN into a single SDK, and how Products, Packages, Offerings, Entitlements, and CustomerInfo connect.
80%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./revenuecat-play-billing/skills/rc-understanding-revenuecat/SKILL.mdUse this skill before writing any RevenueCat code. It gives you the vocabulary and mental model you need so that downstream skills (setup, configuration, purchase flow, entitlements) make sense.
Start here if any of these apply:
Skip this skill if you already know the difference between an Offering, a Package, a Product, and an Entitlement, and you already know that Purchases.sharedInstance is the single entry point.
Raw Android in-app purchases require three separate systems. RevenueCat folds all three into one SDK plus one dashboard.
| Raw Google Play stack | RevenueCat replacement | Where it lives |
|---|---|---|
BillingClient on the client | Purchases SDK | Your Android app |
| Google Play Developer API on your server | RevenueCat backend | RevenueCat managed |
| Real Time Developer Notifications via Cloud Pub/Sub | RevenueCat webhooks | RevenueCat managed, delivered to your server |
The call path is:
Your App
-> Purchases SDK
-> RevenueCat Backend
-> Google Play Developer API
-> Google PlayYour app talks to the Purchases SDK. The SDK talks to Google Play for the purchase UI and to the RevenueCat backend for verification and entitlement storage. Your server side code talks to the RevenueCat backend, not to Google Play directly.
One consequence: RevenueCat sits in the purchase verification path. After a user completes a purchase, the SDK posts the token to RevenueCat before your app sees confirmation. You trade a network round trip for not having to build server side verification yourself.
| Concept | What it is | Where you define it |
|---|---|---|
| Product | A subscription, base plan, or one time purchase | Google Play Console |
| Package | A Product wrapped with a type label (Monthly, Annual, Lifetime, custom). The unit your paywall displays | RevenueCat dashboard |
| Offering | A group of Packages. One Offering is the Default offering and is returned by offerings.current | RevenueCat dashboard |
| Entitlement | A logical access level your app checks, such as "pro_access". Products are attached to Entitlements | RevenueCat dashboard |
CustomerInfo is the runtime snapshot of the user's purchase history and active Entitlements, computed and cached by RevenueCat.
val offerings = Purchases.sharedInstance.awaitOfferings()
val monthly = offerings.current?.monthlyval customerInfo = Purchases.sharedInstance.awaitCustomerInfo()
val hasPro = customerInfo.entitlements["pro_access"]?.isActive == trueisActive already resolves the eight Play subscription states (ACTIVE, IN_GRACE_PERIOD, ON_HOLD, PAUSED, CANCELED, EXPIRED, PENDING, PENDING_PURCHASE_CANCELED) on the server side. You do not reimplement that logic on the client.
Purchases.sharedInstance is the single entry point. You configure it once at app startup:
Purchases.configure(
PurchasesConfiguration.Builder(context, "your_api_key")
.appUserID("optional_user_id")
.build()
)Unlike BillingClient, the singleton does not require you to manage connection state. It reconnects and queues calls for you.
You offload verification complexity and take on a dependency. If the RevenueCat backend has an outage, purchase verification is affected. Two mitigations exist and they are different:
| Feature | What it does | When it kicks in |
|---|---|---|
Disk cache of CustomerInfo | Returns the last known server state for entitlement checks | Automatic, always on |
| Offline Entitlements | Computes subscription entitlements on the device from local Play Store purchases and the cached product to entitlement mapping | Automatic when RevenueCat's servers return errors. Not for one time purchases, and off when your app completes purchases itself |
Neither is a full substitute for a reachable backend. Use both where they apply.
Once you have the model above, pick the next skill based on what the user actually wants to do.
| User goal | Next skill |
|---|---|
| Create the dashboard project, connect Play service credentials, create entitlements and offerings, get the API key | rc-setup |
Add the Gradle dependency, call Purchases.configure, pass an appUserID, set log level | rc-configuring-the-sdk |
Fetch Offerings, show a paywall, call purchase, handle the result | rc-purchase-flow |
Check customerInfo.entitlements["..."]?.isActive, gate features, listen for updates | rc-subscription-states |
| Identify, alias, or log out a user | rc-configuring-the-sdk (app user id strategy) and rc-subscription-states (logIn/logOut) |
| Handle restore purchases, cross device, promo codes | rc-purchase-flow (Phase 5) |
| Receive server side events from RevenueCat | rc-webhooks |
| Debug a specific purchase, receipt, or entitlement in production | rc-error-handling or rc-testing |
If the user's goal does not match any row, stay here and keep clarifying intent before routing.
Before you leave this skill and route to a downstream one, confirm out loud:
Offerings (what to sell) or CustomerInfo (what the user already owns). Most confusion comes from mixing these two.If any of the four fail, reread Phase 1 or the chapter before proceeding.
RevenueCat/ai-toolkit
2aeae8c
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.